When you think of user documentation authoring systems, a couple of traditional tools often come to mind: FrameMaker, Microsoft Word, InDesign, RoboHelp, LyX, TeX files, MadCap Flare. Some are fully proprietary, while others embrace some standards. Some are semantic, while others are design driven.
With the evolving output formats that are present today (and tomorrow, for the future predictors), there is honestly no excuse to have your primary authoring environment be non-semantic. For the uninformed, semantic implies meaning – instead of making text large, you mark it as a section, or instead of indenting and changing the color of text, you denote that the text is a call-out or note.
Many editors, even our friend who can’t typeset Microsoft Word (thats another topic), have semantic capability integrated. You define headers, sub-sections, footnotes, and more. Systems such as FrameMaker and LyX are heavily geared for this workflow – they in fact make it a relative pain to not follow their conventions. Systems such as RoboHelp attempt to be semantic, but are so steeped in legacy that they become unusable: RoboHelp still depends on VBA macros and Word to generate PDFs – this is an Adobe product by the way.
What about semantic file formats which are designed for direct editing – preferably human readable or approachable? There are really two main contenders in my eye, and one of them you may not be considering: DocBook and Sphinx wih reStructuredText.
First there is DocBook. Its a standard. It was formally SGML and now XML. There are tools, XSLT transforms, and the like to output a variety of formats, include LaTeX typeset documents, webpages, and Windows Help files. However, its incredibly unfriendly for human editing. No one likes hand-writing XML – its simply not natural, even as much as HTML has established its self. DocBook is also an ecosystem – there are tools, but they all have different ideas of what they should do, and interoperability is not guaranteed.
What if you could fix the human problem and provide a better semantic system, one with a kick-ass implementation (and not an ecosystem)? Thats what Sphinx does. It is DocBook for humans. You may know Sphinx as a Python API documentation system. It is, and it excels at that job like none other. However, Sphinx is both extendable, and composable – if you never ask for API documentation, it will never give you any. It also typesets using LaTeX, spits out theme-able and gorgeous webpages, and even makes Windows Help files. And if your document has special needs, its very easy to extend to produce end user documentation.
The real question is how well suited Sphinx actually is for writing non-developer user manuals. How easily can you get a technical writer versed in reStructuredText? How easy is it to actually change the look and feel of a document? From my initial investigation, I see few issues. However, the only way to actually know is to drink the Kool-Aid. My test will be to create an end-user manual, involve non-coder friends, and identify strengths and weaknesses.
I feel that Sphinx is everything DocBook promised, delivered.
.
