Building from the ground up summarizes the documentation approach we advise:

  • Start with basic in-situ documentation and attach it to the software interface,
  • If possible contextualize this information,
  • Then write the other forms of documentation as needed.

Why start from the ground and build up?

Well, it’s the oldest architectural approach in the world.

It ensures that you have covered the essentials and in the right place, where the user needs it, easily accessible in front of him.

What is in-situ contextualized documentation?

Our information block approach becomes particularly useful when dealing with in-situ documentation delivered to the software GUI, to devise a matrix of information determined d by asking the right questions:

  • What is this and/or what does it do?
  • How do I use it?
  • Do I have an example?
  • Where am I in terms of a workflow?
  • What next?
  • What pitfalls to avoid?

This is an editorial matrix, a content guideline as sorts. By no means are all items to be written exhaustively as if they were a form to be filled. It helps the writer to ask the right questions.

Other forms of documentation as needed?

All other forms of information as considered as additional, for instance, related FAQs, Workflow steps, Concepts and Theory or even what DITA calls reference information.

The kinds of software we encounter cater for procedures that are inherent in a technical domain. Users of the software know at least a little about the domain in question. Generally we don’t have to teach them their business, but how the software helps them do this.

Nowadays, agile approaches to software development aim at tailoring and fine tuning software to exactly what is expected and accepted by users. Theoretically this alleviates the documentation load.

What then needs to be explained?

  • Particular approaches adopted by software – inherent procedures.
  • Concepts developed to help the user find his way around.
  • Terminology if it is unfamiliar.
  • Pitfalls to be avoided.
  • Illustrative examples of results.
  • A corpus of frequently asked questions that can be used in support of the software