At the top of the file should be a short introduction to the topic being covered in this document. This introduction should concisely explain what this guide is about in general terms.
The overview expands on the introduction above by explaining some of the details around the actual discussion in this document. This is a place for establishing any prerequisites for following along.
Other things that should be explicitly addressed in the overview are:
- Stating who the intended audience is
- Explaining any assumptions that are made in the document
- Listing any prerequisites around system requirements, required reading, etc.
Make sure to add any additional direction for people who do not meet the prerequisites. This can be something as simple as adding links when detailing the prerequisites, it's important to use this section as a way to redirect people who may have ended up in the wrong place.
Each topic guide should include at least one section composed of at least two parts:
- A short introduction and or overview
- Tasks on how to accomplish work laid out in this section
The section introduction should be added here and follow any appropriate guidelines about introductions and overviews from above. The template laid out here for sections can be nested or repeated as needed.
The individual tasks for a section should be laid out following the section's introduction. Each task should have a short description of what is being accomplished and how the task relates to the documents discussion.
At the most granular level, examples should be included along with detailed instructions. It is important to do more then just parrot a walk through of source code, the explanations of the examples are critical to the understanding of the document as a whole.
// Add any example code following the instructions that show **how** to
// accomplish the task. These should be working code samples that can be
// cut and pasted by any reader following along.
Any example should be followed by detailed descriptions about why the code above accomplishes the task, make sure to include specific API documentation or other documentation references where appropriate.
Some short notes about simple things that can help explain potential problems or misunderstandings should go here. This section should address what to do if things go wrong while following along with the task; guidelines, best practices, notes about common errors or mistakes, explanations of pitfalls, links to FAQs, etc.
If larger explanations beyond a paragraph or so and a few guidelines are required try adding a short hint here then linking to details at the bottom of the page. Use your best judgement for what is an appropriate amount of details to balance while not breaking the flow of the guide for readers that are not having trouble.
After the topic of the document has been effectively covered use this section to provide a short summary along with a list of things that could be explored further. This can include a list of other related topic guides, API references, links to libraries, example implementations, etc.
If someone read this far they didn't get what they needed so make it easy for them to discover where they can go to get more details or help. This section should cover in detail any problems, edge-cases, common pitfalls, and warnings that may come up which were not covered in the document up to this point. It should also include an additional section about how to get additional help if the problems experienced can not be resolved by the details laid out here. Things that can help are links to FAQs, contact pages, IRC, or anything else you think might be helpful.