Jump to: navigation, search

Guides are a very important form of documentation. It should be the bulk of documentation on a project. Each guide should be a comprehensive deep-dive into a particular aspect or feature of the software. When a user has read a guide all the way through, they should feel like they should have a strong understanding of the topic. Combined with tutorials and references, guides will provide a user will all the knowledge they need to use the software in almost all cases.

To get a sense of guide topics, let's look at OpenWrt. If we started from scratch, some of the prplwrt guide topics might be:

  • Security and authorization mechanisms
  • Wifi
  • Package manager
  • Build system

Each of these topics is large and focuses on a particular area of the software. Each is relatively self-contained so that a user is only getting the information related to the topic. By compartmentalizing into topics the documentation is broken into manageable chunks.

In some situations topics may build upon other topics. If this simply can't be avoided, it should be clear which topics are prerequisites and it should be easy to understand the flow of the topics. In the same way as a person would use a table of contents in a book, the flow should be clearly documented and easily discoverable.