Software Documentation Structure
We encourage software development teams to apply this documentation structure across all projects. This way the reader could learn it from a single software project and then quickly navigate through a familiar structure across the whole wiki. It also gives you a starting point to start writing documentation, and it makes it easier to maintain the wiki in general.
This structure is based on the Diataxis framework by Daniele Procida. As the author describes it:
The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product.
Diátaxis identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation. It derives its structure from the relationship between them.
In Diátaxis, each of these modes (or types) answers to a different user need, fulfils a different purpose and requires a different approach to its creation.
The documentation should be split in the following folders: Getting Started, How Tos, Tutorials, Explanations, and Reference and the following files: Welcome, Troubleshooting, and Contribute. You do not have to use all of these sections.
Welcome
The Welcome article is the first page of your project documentation. Tell the reader what your project is about and provide links to the GitHub repository and additional resources like roadmaps, educational materials, or research specifications.
Getting Started
The Getting Started folder should be the first section in your documentation. It should give the user a high-level overview of the project, required prior knowledge, prerequisites, and ideally a quick setup guide, or "hello world".
How Tos
The How Tos folder should only address concrete examples, or how-to guides, which are goal-oriented.
Tutorials
The Tutorials folder should contain articles which guide the user step by step through a series of how-tos with the relevant explanations to achieve a project or real world use case. Tutorials are learning-oriented.
Explanations
The Explanations folder revolves around explanations, and is understanding-oriented.
Reference
The Reference folder should describe the technical information of your project. It is information-oriented.
Troubleshooting
The Troubleshooting file should contain instructions or links to where users can post questions, or create issues if necessary.
Contribute
The Contribute file should encourage users to contribute to the project and contain directions for that.