Speaker Deniele Procida
Time 2017-08-06 11:25
Conference PyCon Au 2017

What nobody tells you about documentation

  • Better documentation will make your project more successful.
  • We are reliant on people choosing to use our software.
  • Even if you can force people to use your software, then won’t use it well.
  • Most people fail.
  • Probably: You are doing wrong.

The right way is the easier way.

There are 4 things represented by documentation.

  1. Tutorials.
  2. How to guides.
  3. Discussions.
  4. Reference.

These should be kept separate from each other.


Teaching. Inspiring confidence in the students so they will come back.

Learning orientated.

Immediate sense of achievement. Attention span is short, but as long as they keep coming back, they have sense of improvement.

Do distractions. No unnecessarily details.

Should be repeatable, bullet proof.

Tutorials should not be mixed with how to guides.

How to guides

Serious of steps to solve a common problem.

Problem orientated.

In a tutorial, you know the problems. You need to instruct the user what problems they need to solve.

In a how to guide the user now knows what problems they want to solve.

Need to be reliable, but don’t need to be bullet proof like tutorials.

Focus on the goal. No unnecessarily explanations.

Little Flexibility.

Good name important.


One job: description.

Information orientated.

Technical description, how to use.

Structure, consistency, description, accuracy.


Explanations, background material, clarify particular topic.

Understanding orientated.

Not place for instruction or technical description.


Put the wrong part in the wrong place, and you will upset the balance of the documentation.

It is difficult to get this right, and to keep them separate.



These rules should apply to wikis. Wikis are bad at this. To much temptation just to dump extra information any place. Resist the inward forces. Resist the urge to combine the different types of documentation.