TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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, https://www.w3.org/standards/webdesign/accessibility, 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,
-Monique
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
