https://documentation.divio.com/

[                    ] 
  * 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

Cloud deployment by Divio

There's a better, faster, easier way to develop, deploy and manage
web applications.

Find out more at Divio
Documentation system
Divio

  * Docs  >> 
  * The documentation system

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.

Video presentationP

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

Next
---------------------------------------------------------------------

(c) Copyright 2020, Daniele Procida. Revision 12d00748.

Edit on GitHub

Documentation v: latest

Versions
    latest

Downloads
    pdf
    html
    epub