Before starting to write content, you should define the documentation structure to answer questions such as:
- How many sections do I need?
- What should each section cover?
- Do some sections need sub-sections?
Answering these and other questions will help you scope the project and define the content that needs to be found or written.
Keep in mind that although you should decide on the structure of your site at the beginning, you might need to make changes as you gain a deeper understanding of the content. With Presidium, it’s easy to change the structure by moving articles.
The Presidium templates are pre-configured with a standard menu structure that you can use to start scoping your documentation. You can add new sections but in most cases, the standard sections will suffice.
The following table shows the pre-configured sections in the software documentation template:
| Section | Description |
|---|---|
| Overview | A brief, business-level overview of the solution that includes the main benefits vs. alternative solution |
| Key Concepts | Introductory descriptions of the solution’s key concepts, components, and structures that include roles and responsibilities for the component. |
| Prerequisites | A summary of the required knowledge, skills, and software to successfully use the solution. |
| Best Practices | The recommended approach for using the solution. |
| Reference | Information on the technical content of the site. APIs, data structures, etc. Reference material should also include detailed descriptions of how to use each part of the solution, arranged by conceptual area. |
| Recipes | A solution for a specific problem or a way to achieve a specific objective. Recipes are used to show a user how to do something. |
| Glossary | A list of definitions for terms that have specific meanings in the solution documentation. |
| Use Cases | Descriptions of how the solution’s components work together to enable commonly implemented scenarios. Use cases should include code examples. |
| Tools | A list of tools and services that can be used with the solution. |
| Updates | New releases, patches, or other announcements of interest to the user community. |
Discussion
After you have identified the sections you want to use for your documentation, define and compile a list of the learning objectives for each section.