nikclayton

Suppose you have to write some documentation. It might be a tutorial, a how-to guide, or an explanation of a topic (see Diátaxis for more on those).

Challenges when doing this include:

• Deciding how to structure the document.
• Deciding when the document is complete.
• Over-stuffing the document with information that is not relevant to the reader at that time.
• Ensuring the reader has the necessary prerequisite knowledge to understand the material.

To combat those problems start the document with a “Synopsis” section that consists of:

• 1-n paragraphs that provide a very brief introduction to the topic. That might be an overview of the topic, or perhaps a description of the specific problem the documentation will help you solve.
• A list of 0-n bullet points that start “Before reading this document you should:“.
  • Each bullet point should link to material that explains how the reader can complete the task. That might be an activity they need to complete, or a document they should read before this one.
• A list of 1-n bullet points that start “After reading this document you will know:”

I have found this to be invaluable when organising your thoughts.

1. If you cannot write a brief introduction to the topic that is an indication you either do not understand it well enough to write about it, or the topic is too complex to cover in a single document and should be separated into smaller documents.
2. The “... you will know” bullet points serve several functions:
   1. They're your “to-do list” of things to write about in the document. You know the document is complete / ready for editing when you have ticked off each bullet point.
   2. If you find yourself writing more than ~ seven bullet points that's a good sign the document is going to be too complex, and should be broken in to smaller documents.
3. Similarly, the “... you should:” bullet points have several functions:
   1. They allow you to be explicit about what is not covered in the document.
   2. They clearly direct the reader to the other material.
   3. They highlight material that may be missing. If you find yourself writing an entry in this section but do not have documentation that tells the user how to complete this task you have discovered another document you need to write.

This works whether you are writing a stand-alone document or one that is part of a collection.

I first adopted this technique when I was co-editing the 2nd edition of the FreeBSD Handbook, and although that is long in the past, today's handbook continues the tradition.

The synopsis for the “Wayland” chapter is a good example. It starts:

An installation of FreeBSD using bsdinstall does not automatically install a graphical user interface. This chapter describes how to select, install, and configure a Wayland compositor, which provides a graphical environment.

Before reading this chapter, you should:

• Know how to install additional third-party software.
• How to identify and configure drivers for your graphics hardware.

After reading this chapter, you will know:

• How to configure FreeBSD to host a Wayland graphical environment.
• How to install and configure a Wayland compositor.
• How to run programs designed for the older X Window System.
• How to configure remote desktop access to a Wayland graphical environment.

In that example:

• The introductory paragraph provides context for the reader.
• The “... you should:” bullets clearly explain prerequisite knowledge, and direct the reader to the right place to learn that knowledge.
• The “... you will know:” bullets tightly scope the content of the document, and allow the reader to rapidly determine whether this document is going to be helpful for whatever task they are carrying out.

---