Documentation

Older notes in the Abilian Dev Guide:

• https://abilian-developer-guide.readthedocs.io/en/latest/documentation.html

Books

• Docs for Developers: An Engineer’s Field Guide to Technical Writing (2021)

Recommendations

• https://refactoringenglish.com/chapters/rules-for-software-tutorials/

The “4doc” / Diátaxis model

• https://www.hillelwayne.com/post/problems-with-the-4doc-model/
• https://docs.divio.com/documentation-system/
• https://diataxis.fr/

“The core idea of Diátaxis is that there are fundamentally four identifiable kinds of documentation, that respond to four different needs. The four kinds are: tutorials, how-to guides, reference and explanation. Each has a different purpose, and needs to be written in a different way.”

The Seven Action model

• https://passo.uno/seven-action-model/

The Seven-Action Model is based on seven actions that users typically perform when interacting with documentation:

1. Appraise (Discern): Evaluating the product’s qualities and comparing it to others.
2. Understand (Learn): Grasping the fundamental concepts behind the product.
3. Explore (Discover): Experimenting with the product and discovering its features.
4. Practice (Train): Learning how to perform specific tasks.
5. Remember (Recall): Looking up specific information, like parameters or error codes.
6. Develop (Integrate): Building upon or extending the product’s functionality.
7. Troubleshoot (Solve): Diagnosing and resolving issues.

Norms

• ISO 16016 - specifies the protection notices which serve to prevent the improper use of documents and products whose usage is restricted.

#documents

Page last modified: 2025-01-12 02:57:47