QuickStatements 3.0/Documentation
Documentation is any written or visual material used to explain, describe or instruct attributes of an object, system, or process. In software development, documentation explains how a software works, how to use it, how to contribute to it, and how to solve common problems, known as debugging. It includes a variety of materials, such as API references, installation guides, tutorials and FAQs, and enables users to learn how to use a tool efficiently, as well as it helps new developers onboard quickly and supports maintainers in debugging and implementing or modifying features. It also promotes transparency in how a project was, is and could be developed, especially in collaborative and open-source projects such as this.
Without good documentation:
- Newcomers struggle to start using the tool.
- Experienced users find difficult to use new features.
- Developers spend too much time trying to understanding the codebase.
- Teams lose consistency in workflows and implementation details.
- Projects become harder to maintain, scale, and adapt.
Diátaxis framework
[edit]
The Diátaxis framework offers a structured and user-focused approach to organizing documentation. It is a theory of documentation that divides a skill into two complementary parts–action and cognition, respectively pratical and theoretical knowledge–, and defines the user's relation to those parts also into two–acquisition and application, respectively studying and applying the knowledge. That creates 4 types of documentation:
- Tutorials: Focused on learning how to use the tool
- How-to Guides: Focused on how to use specific features of the tool
- Reference: Focused on describing the system in detail
- Explanation: Focused on the underlying concepts and decisions about the tool
We believe that this approach to documentation solves what we see as a common problem in documentation: mixing audiences and purposes in a single page or section. Separating the documentation into axis and pages helps ensure that everyone gets what they need without having to interact with the whole documentation, making the user experience more intuitive and effective.