Best practice for writing reusable documentation
Our company has a fairly small product line, but the use can be quite complex.
The current situation is that (internal and external) documentation is distributed in different places: Wiki, Adobe Indesign files, documents, text files, inline documentation in code, help texts in the web interface of our products, etc. The documentation was written by a small group of developers, but it is almost impossible to track all changes if you want to update all other sources.
In general, we want to provide the following types of documentation (sorted by difficulty).
- Quick Start Guide
- User's manual
- Help texts in webinterface
- Administration Guide
- Tutorial
- Internal documentation (for developers)
Much of the content is the same for all guides (general information), some of the content is in only the last three types, and the internal documentation should contain all of the content.
I have looked at some of the tools that are often recommended for 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 these two tools also seem very complicated and the user is unfriendly.
Of course, one could only use LaTeX and only include the parts that are appropriate for the type of documentation you want to build. But that looks like a solution to the problem.
So I'm wondering:
- Is there a best practice for writing reusable documentation?
- How do large (ger) companies manage their records?
- Is there a way to have all the documentation in one place and compile different versions for different target groups without manually handling the changes?
For internal documentation, it would be nice to include parts of the code, but it's not required. It would also be nice to use version control (git) to save the content.
source to share
It sounds like you are looking for a single source documentation tool like Author-It or MadCap Flare . They allow you to write topics once, and then insert those topics into multiple documents (so when you make changes, you only need to do it in one place).
They also make it easy to create multiple output formats from the same content, for example. An HTML version of your admin guide for your site and a PDF to send with the product.
Hiring a tech writer to help you get set up is probably a good investment.
source to share
DITA is built for this and offers many reuse mechanisms such as keyrefs, conkeyrefs, filters, etc. You can find a video here that explains these mechanisms. You must carefully weigh whether or not to rely on a proprietary tool / format for your documentation (for example, use Author-It or MadCap or any other competing tool). It may be a one-way street with no return points. If you want to switch your documentation toolset eg. because your supplier increases prices or stops support for your instrument, you have a problem. DITA is probably more expensive, but it is an open standard.
source to share