How to write documentation (Bookstack)

Bookstack is the software you are reading this on right now! Some guidelines for writing documentation:

Make large books

Bookstack organizes things into "books", "chapters", and "pages". Books are meant to be read or skimmed linearly, like a real book with a real table of contents. this means you should use the "sort" function liberally, to keep books in a rough information hierarchy, and putting two pages in the same book/chapter is a good way to make sure that a reader sees both.

Page titles are searchable, Page contents are not

the search bar at the top of the page can pull up any page based on what's specifically in the title of that page. this means that an ideal title will include key words that make it easy to search for. Information buried in a sub-heading will probably be harder to search for, which may or may not be a good thing.

Stay current

If something is out of date, update it! Avoid referencing changes that will happen, or are planned to happen.

Consider the purpose of your doc

Where possible, try to figure out if your doc is meant to be:

• A reference, recording abstract information for later
• A how-to guide, describing how to do a concrete thing
• An explanation, describing why and how things got to be the way they are
• Or a tutorial, which is a guided how-to guide that is meant to teach the reader.

This is known as the Diátaxis system.