Writing tools

Which writing tool should I use for my documentation?

For a straightforward account on choosing a documentation tool, see the article in Wouter Veeken’s blog. I’m quoting liberally from Wouter’s site below. The choice of 83 experts is shown on the Instrictiv site. The top two were MadCap Flare and DITA xml.org. Greg Babb has made a search engine for choosing a documentation tool, at https://doctoolhub.com/

Basically you can choose between one of the following:

1. A proprietary help authoring tool (HAT)

Examples of HATs are Adobe RoboHelp, AuthorIT or MadCap Flare. You purchase the package, install it, learn how to use it and start writing.

Advantages: you have one location where you design, write and publish your docs in several formats (e.g. html, pdf, xml, docx); in many cases there’s not a huge learning curve involved.

Disadvantages: you’re locked in to a specific package, so you’re fully dependent on the features offered by the package, which may or may not be what you really want. It’s a bit of a “black box”, and you might only become aware of this after working with the package for a few months. You may have to tinker with the results produced before you can publish them, for example you might have to ‘hack’ a bunch of html files after these are generated by your package in order to get the results you’re looking for.


2. A Wiki platform

A wiki is a “website or database developed for and by a community of users, allowing any user to add and edit content”. In a typical wiki, text is written using a simplified markup language. Wiki invites all users—not just experts—to edit any page or to create new pages within the wiki Web site, using only a standard “plain-vanilla” Web browser without any extra add-ons.

Advantages: if you’re working in a team of software developers, everyone adds their contribution easily and without having to conform to a predefined structure.

Disadvantages: wiki’s flexibility is at the same time its weakness, its lack of structure means that information becomes disorganised easily. This can make life very hard for a technical writer who is trying to create structured documentation.

For more info, see a list of wiki software and a wiki choice wizard.


3. Static site generators

This is where a group of developers and writers work together using a version control system such as Git (the Docs as Code approach). The writers use a lightweight markup language such as Markdown and store it in the Git repository. The Static Site Generator (SSG) turns this content into a set of static (as opposed to dynamic) HTML files which are then uploaded to a website. So you’re treating docs like code, using the same systems, processes and workflows.

Advantages: you can choose your own (free) text editor and your own markup language, your own source control environment, your own hosting solution etc. The content format is familiar to programmers, which may encourage contributions. Many popular SSGs are open-source.

Disadvantages: an SSG requires a fairly technical person to maintain it and you should be comfortable with command line interfaces, HTML, CSS, and checking code out of and into repositories.

For more info, see the arguments for and against using a SSG.


4. An XML-based documentation system

(Thanks to Richard Lewis for this example).

Let’s say you’re writing the following note:

To: Sally

From: Benny

Title: Shopping

Pick up some milk.

Now here’s the same document written In XML:

<note><to>Sally</to><from>Benny</from><heading>Shopping</heading><body>Pick up some milk.</body></note>

For the XML document you first create <tags> for the following: the type of document <note>, the recipient <to>, the sender <from>, the header <heading> and the actual note <body>. You’re creating a predefined structure, or set of rules for the note, for example you could also specify that each note must have one or more recipients but only one title. If you were writing the same note in an MS-Word file, there is of course no document structure. In XML you can enforce structure in your documents.

XML stands for eXtensible Markup Language, and is a subset of SGML (Standardized General Markup Language). XML is a text markup language, not really a database, i.e it does not have the same facilities as Oracle or Access.

Here are two articles outlining what XML is, from Richard Lewis and Peter Flynn. Intimately connected with XML is the concept of DITA (Darwin Information Typing Architecture). DITA is a model for authoring and publishing topic-based content. For a short overview of DITA, see Topic Base Authoring.