RE: criteria for choosing tools ?

Subject: RE: criteria for choosing tools ?
From: "Annette Reilly" <annette -dot- reilly -at- computer -dot- org>
To: "'Monique Semp'" <monique -dot- semp -at- earthlink -dot- net>, "'TechWR-L'" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 14 Mar 2017 09:40:59 -0400

Though it doesn't discuss advantages of specific products and is light on publishing/output systems, there's a standard with thorough requirements for a content management system: ISO/IEC/IEEE 26531:2015, Software and systems engineering â Content management for product life-cycle, user, and service management documentation. It begins with how to choose systems and considering how they will change your workflow, rather than getting a tool and then thinking of how it will fit or change your way of operating.

-----Original Message-----
From: Monique Semp [mailto:monique -dot- semp -at- earthlink -dot- net]
Sent: Monday, March 13, 2017 9:00 PM
To: TechWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: criteria for choosing tools ?

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 @

criteria for choosing tools ?: From: Monique Semp

Next by Author: RE: User Documentation in Agile Development Teams
Previous by Thread: Re: criteria for choosing tools ?
Next by Thread: Re: criteria for choosing tools ?

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

Sponsored Ads