https://documentation.divio.com/

 

  * Product
  * Services
  * Developers
  * Pricing

  * Sign in
  * Sign up for free

[ ] [ ]
Hide navigation sidebar
Hide table of contents sidebar
Toggle site navigation sidebar
 
Documentation System
Toggle Light / Dark / Auto color theme
Toggle table of contents sidebar
 
[                    ] 
  * Introduction[ ]
    Toggle child pages in navigation
      + The problem and the solution[ ]
        Toggle child pages in navigation
          o The problem it solves
          o The 'secret'
      + Making documentation work[ ]
        Toggle child pages in navigation
          o For authors
          o For readers
  * Tutorials[ ]
    Toggle child pages in navigation
      + Analogy from cooking
      + How to write good tutorials[ ]
        Toggle child pages in navigation
          o Allow the user to learn by doing
          o Get the user started
          o Make sure that your tutorial works
          o Ensure the user sees results immediately
          o Make your tutorial repeatable
          o Focus on concrete steps, not abstract concepts
          o Provide the minimum necessary explanation
          o Focus only on the steps the user needs to take
      + Example from Divio's documentation
  * How-to guides[ ]
    Toggle child pages in navigation
      + Analogy from cooking
      + How to write good how-to guides[ ]
        Toggle child pages in navigation
          o Provide a series of steps
          o Focus on results
          o Solve a particular problem
          o Don't explain concepts
          o Allow for some flexibility
          o Leave things out
          o Name guides well
      + Example from Divio's documentation
  * Reference guides[ ]
    Toggle child pages in navigation
      + Analogy from cooking
      + How to write good reference guides[ ]
        Toggle child pages in navigation
          o Structure the documentation around the code
          o Be consistent
          o Do nothing but describe
          o Be accurate
      + Example from Divio's documentation
  * Explanation[ ]
    Toggle child pages in navigation
      + Analogy from cooking
      + How to write a good explanation[ ]
        Toggle child pages in navigation
          o Provide context
          o Discuss alternatives and opinions
          o Don't instruct, or provide technical reference
      + Example from Divio's documentation
  * About the structure[ ]
    Toggle child pages in navigation
      + Why isn't this obvious?[ ]
        Toggle child pages in navigation
          o The tendency to collapse
      + Adoption of the system
      + About the analysis and its application
  * Who is using the system?[ ]
    Toggle child pages in navigation
      + Other mentions and references of interest

  * Docs  >> 
  * The documentation system

Toggle Light / Dark / Auto color theme
Toggle table of contents sidebar

The documentation systemP

The Grand Unified Theory of Documentation

- David Laing

There is a secret that needs to be understood in order to write good
software documentation: there isn't one thing called documentation,
there are four.

They are: tutorials, how-to guides, technical reference and
explanation. They represent four different purposes or functions, and
require four different approaches to their creation. Understanding
the implications of this will help improve most documentation - often
immensely.

About the systemP

'overview of the documentation system'

The documentation system outlined here is a simple, comprehensive and
nearly universally-applicable scheme. It is proven in practice across
a wide variety of fields and applications.

There are some very simple principles that govern documentation that
are very rarely if ever spelled out. They seem to be a secret, though
they shouldn't be.

If you can put these principles into practice, it will make your
documentation better and your project, product or team more
successful - that's a promise.

The system is widely adopted for large and small, open and
proprietary documentation projects.

  * Introduction
      + The problem and the solution
          o The problem it solves
          o The 'secret'
      + Making documentation work
          o For authors
          o For readers
  * Tutorials
      + Analogy from cooking
      + How to write good tutorials
          o Allow the user to learn by doing
          o Get the user started
          o Make sure that your tutorial works
          o Ensure the user sees results immediately
          o Make your tutorial repeatable
          o Focus on concrete steps, not abstract concepts
          o Provide the minimum necessary explanation
          o Focus only on the steps the user needs to take
      + Example from Divio's documentation
  * How-to guides
      + Analogy from cooking
      + How to write good how-to guides
          o Provide a series of steps
          o Focus on results
          o Solve a particular problem
          o Don't explain concepts
          o Allow for some flexibility
          o Leave things out
          o Name guides well
      + Example from Divio's documentation
  * Reference guides
      + Analogy from cooking
      + How to write good reference guides
          o Structure the documentation around the code
          o Be consistent
          o Do nothing but describe
          o Be accurate
      + Example from Divio's documentation
  * Explanation
      + Analogy from cooking
      + How to write a good explanation
          o Provide context
          o Discuss alternatives and opinions
          o Don't instruct, or provide technical reference
      + Example from Divio's documentation
  * About the structure
      + Why isn't this obvious?
          o The tendency to collapse
      + Adoption of the system
      + About the analysis and its application
  * Who is using the system?
      + Other mentions and references of interest

Video presentationP

If you'd prefer to watch a video covering this topic, here is it
(courtesy of PyCon Australia 2017).

Copyright (c) 2022 Divio Technologies AB | Show Source Edit on GitHub
In this page

  * The documentation system
      + About the system
      + Video presentation