Best practice for writing reusable documentation

Question

Our company has a rather small product line but the usage can be quite complex.

The current situation is that the (internal and external) documentation is spread over various places: Wiki, Adobe Indesign files, docs, text files, inline documentation in the code, help texts in the webinterface of our products etc. The documentation is written by a small group of developers but keeping track of all changes is nearly impossible if you want to update all of the other sources.

In general, we want to provide the following kinds of documentation (sorted by raising complexity).

• Quick start guide
• User guide
• Help texts in webinterface
• Administration manual
• Training manual
• Internal documentation (for developers)

Much of the content is the same for all of the manuals (general information), some of the content is just in the last three types and the internal documentation should contain all of the contents.

I've had a look at some tools which are often recommended on stackoverflow (namely DITA, docBook, pandoc, doxygen, Sphinx). Except for DITA (or DITA OT) and docBook, none of the tools seem to focus on reusable content. But those two tools also seem to be very complex and user unfriendly.

Of course it would be possible to use just LaTeX and include just the parts suited for the type of documentation you want to build. But this seems like a workaround solution to me.

So I am wondering:

• Is there a best practice on how to write reusable documentation?
• How do big(ger) companies manage their documentation?
• Is there a way to have all documentation in a single place and compile different versions for different target groups without handling the changes by hand?

For internal documentation it would be nice to include parts from the code but it's not mandatory. It would be also nice to use version control (git) to maintain the content.

Answer 1

Sounds like you're looking for a single-sourcing documentation tool, such as Author-It or MadCap Flare. These let you write topics once and then embed those topics in multiple documents (so when you make changes, you only need to do it one place).

They also make it very easy to generate multiple output formats from the same content, e.g. an HTML version of your admin manual for your website and a PDF one to ship with the product.

Hiring a technical author to help you get set up is probably a good investment.