The Divio Documentation System

The Divio documentation system is a way to make your documentation better, not by working harder at it, but by doing it the right way. This learning hour helps you to understand and use this system.

Learning Goals

• describe four types of user documentation according to the Divio system
• use the system to classify sample pages of documentation
• use the system to write a page of documentation in one of the categories

Session Outline

• 10 min connect: find documentation examples
• 10 min concept: Divio documentation system
• 15 min concrete: classify and evaluate examples
• 15 min concrete: write a document in one of the categories
• 5 min conclusions: how can we use this

Connect: find documentation examples

Web hunt - In your daily work, what documentation do you look at for the software frameworks and libraries that you use? Spend 5 minutes gathering the urls of 3-4 webpages of end-user software documentation you have looked at recently. Check your browser history. If you can remember, note down what you were looking for at the time and whether the documentation helped you.

Be ready to share your urls with the group.

Note - this is a Web Hunt.

Concept: Divio documentation system

Explain the four categories in the Divio documentation system using resources from that site.

Concrete: classify and evaluate examples

Working in pairs, look through these urls and classify them into one of the four documentation categories.

• CoReport
• NumPy
• Django
• matching

(Note, all those links are from projects listed as using the Divio system)

When you have done that, go back to your own lists of documentation you have looked at recently. Pick one. How would you classify it? Does it fit neatly into one of the categories or is it a mix of more than one? When you were looking for this documentation, were you studying or working? Were you looking for practical steps or theoretical knowlege? Does that match the document’s classification according to the Divio system?

Concrete: write a document

Pick a tool or library that you know well. Alternatively imagine some part of the the Instavoiced software Write a short text about it in one of the four documentation categories. When the time is up, share it with the group and have them guess which category it belongs to.

Conclusions: how can we use this

Note for yourself if you see any situations where this documentation classification system could help you to write better documentation for the software you work on.