The first step in writing helpful documentation is to determine who your audience is and what their needs are. During the workshop, we gathered in small groups to discuss these questions. Answers are recorded below.
- Teachers who may need teaching materials.
- Students who may need more concise explanations.
- Clients who require non-technical language.
Different users may need documentation in different formats. For example, videos may draw more people in compared to text-based documentation. Providing a central place to host community-sourced documentation aimed at different audiences can be helpful.
At a high level, it's helpful to think about information architecture. For example, the Processing website provides a single reference web page that organizes features according to meaningful categories, with one-line descriptions of individual features; this serves as a kind of cheat sheet for users, who can click on individual features to zoom in and learn more details. The p5.js project is also working on a new website and a new structure for its documentation to make it even more accessible to users.
At a low level, documentation of individual features can include various components, such as an overview of use cases, working examples, and function signatures with descriptions of parameters (including clearly specified default values).
- A style guide is helpful to ensure consistency and to make project values explicit (readability, translatability, etc.).
- A team is helpful for providing feedback, including people with varying levels of experience if possible (this helps address the curse of knowledge that experts can have).
- Software tools for gauging simplicity of writing (e.g. Hemingway editor).
- Choosing tooling that's accessible to the community and easy to maintain is helpful (e.g. including the ability to write documentation in Markdown).