3

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?

  • What kind documentation are your talking of: end users docs, or docs for other developers? Or is this a library, where the "end users" are other developers? – Doc Brown Feb 9 '14 at 19:09
  • @DocBrown: "end users" are other developers. – user877329 Feb 9 '14 at 19:12
  • @DocBrown: I thought mention "API Reference" implied the audience – user877329 Feb 9 '14 at 19:27
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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.