Outline for technical software documentation

Question

Say I have a software project for which the technical documentation should include

• A license document
• A list of used terminology
• An introduction about what the software does
• A short quick-start guide
• Complete documentation of tools covered by the project
• Documentation of file formats and protocols
• An API Reference
• A list of known bugs
• A todo list
• A set of examples

What is a good order of these points?

How can these points be organized into chapters, sections, subsections, and subsubsections?

One of the tools has an hierarchical configuration structure. Should this structure be represented in the documentation outline (this will result in a really deep outline) or should it be flatted in some way?

Answer 1

For this kind of projects, where software products requires large documentation, you should better not include all the information in one single document.

A good approach to this to have a Workbook for developers which is a set of different documents directly related to the software product.

You may structure your workbook so that it includes

1. A licence document
2. An introduction about what the software does, a short quick-start guide, complete documentation of tools covered by the project, documentation of file formats and protocols, an API Reference, in one separate document
3. The lists of known bugs and todo list in another document
4. A set of example

Thus you will have 4 different documents in your workbook. You will have to name them so that developers could easily understand the content of the document.

Hope this helps