criteria for choosing tools ?

Subject: criteria for choosing tools ?
From: "Monique Semp" <monique -dot- semp -at- earthlink -dot- net>
To: "TechWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 13 Mar 2017 17:59:57 -0700

Hello, WR-L-ers,

I thought I recalled a somewhat recent discussion about factors to consider when choosing tech pubs tools (not just for authoring, but for creating/presenting the docs in a âportal-likeâ environment), but I donât see it. So Iâll start a new discussion...

I have the rare opportunity to recommend tooling for revamping/creating docs (a total of several dozen for the foreseeable future) and making them available to customers. So...

Question 1 (of 2)âIâd like to build a big list of criteria so I can rate how various tools stack up for our needs. Hereâs my list so far; any more suggestions?

a.. Create an organized portal/website w/good navigation.
b.. Port existing docs from Markdown files in existing Jekyll site.
c.. Search capability across all docs.
d.. Analytics (access, bounce rate, etc.).
e.. Private site requiring authentication.
f.. Ability to hide some docs from most customers, and make them available only when so configured for a given user.
g.. Mercurial file versioning (no need for an integrated solution; just listed here for completeness).
h.. Mac support (Iâm fine with a Windows VM on my Mac; not sure if they will be but I hope so because Flare is an early strong contender).
i.. Ease-of-use by non-tech-writers (Iâm expecting/hoping that everyone will realize that in order to get all the pubsey things done, this is a pipe dream, and that itâs analogous to forcing a developer to use Notepad instead of a real IDE).
j.. Supports content reuse at a topic level.
k.. Supports conditional text (I foresee lots of complex condition sets).
l.. Supports variables (lots of instructions that are the same for multiple supporting/integrated software, so variables will be key to publishing all the required combos).
m.. Organize/sort/tag/categorize docs by several factors: audience (admins, developers, etc.), product, product-version, supporting/integrated software versions, when used (proof-of-concept, setup/early use, ongoing), and so on.
n.. Generate PDF output, thatâs reasonably pretty, for offline distribution.
o.. Generate HTML output, thatâs easily branded, for online access.
p.. Fits into CD/CI (continuous development/continuous integration) of the SaaS portion of the product suite.
q.. Handles screenshots by reference.
r.. Handles artwork files by reference.
s.. Handles videos (not sure that Iâll create them, but some tasks seem made for such a presentation).
t.. Supports integrating externally-generated HTML mini-sites (produced by auto-generators for API references).
u.. Enable easily adding mechanism for user feedback.
v.. Supports easy localization management (I donât need it now, but want it in the comparison list).
w.. Creates âaccessibleâ content (per W3C info,, and Section 508 requirements).
x.. (DITA/related-structure isnât an option; Iâm the lone writer, so Iâm not even considering that.)

Question 2 (of 2): Which tools would you include in a side-by-side comparison? Iâm thinking:
a.. MadCap Flare.
b.. Tech Comm Suite (unstructured).
c.. Confluence.
d.. SSG (static site generator) approachâbecause thatâs what they have now and itâs Mac-friendly.

Thanks for your input,
Visit TechWhirl for the latest on content technology, content strategy and content development |


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @


Previous by Author: Trello boards - best practices for Tech Pubs ?
Next by Author: Re: criteria for choosing tools ?
Previous by Thread: Re: Trello boards - best practices for Tech Pubs ?
Next by Thread: Re: criteria for choosing tools ?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads