WriteTheDocs 2017 – What nobody tells you about documentation

Speaker: Daniele Procida Django core developer, community and documentation manager at Divio. Daniele came into programming and the IT world through the django project and the django community. He is also involved with a number of African PyCons.

Documentation in software projects

The success of software projects hinges on the documentation! Since you cannot force people to use software, you need to convince them, and to convince folks, you need to show them why and how to use software. This is what we call … documentation! ✨

Documentation is hard, and many if not most efforts to write documentation just fail. So why do they fail, and what do we need to change?

You're probably doing it wrong

People think there is one thing called documentation … while there actually are four! All of these are needed by software projects, and they need to be kept distinct, up-to-date, and easy to work with both for recipients and authors.

1. Tutorials: Learning oriented

Tutorials are lessons that take the reader by the hand through a series of steps to complete a project or an exercise of some kind, showing the beginner that they can achieve and complete some objective. Tutorials are learning-oriented. They are comparable to teaching a young child how to cook. The most important objectives are:

  • Learning by doing, not by learning concepts
  • Getting started, gaining initial interest and experience
  • Inspiring confidence by providing a sense of achievement and success
  • Repeatability of the project/thing
  • Immediate sense of achievement in every step, no matter how small
  • Concreteness, not abstraction ('build this thing', not 'build an example of this concept')
  • Minimum necessary explanation
  • No distractions with implementation details, technical asides, or alternatives

Tutorials provide a teacher-student relationship between the author and the reader, with the author selecting the path and details, and the student following along. Tutorials get users to do something. Tutorials are hardest to write, and need to be good enough to replace a physically present teacher.

2. How-to : Problem oriented

How-to Guides take the reader through the steps required to solve a common problem. Guides are goal oriented. Going with the food examples, they are a recipe. They are very distinct from tutorials, since they answer specific questions, that beginners wouldn't know how to ask. How-to guides are fun and easy to write, and expect the reader to already know what their problem is.

  • A series of steps
  • Assumption of basic competence
  • A focus on the goal
  • Addressing a specific question
  • No unnecessary explanation
  • A little flexibility
  • Practical usability over completeness

Guides should not explain concepts, since that just gets in the way of the goal.

3. Explanations: Understanding oriented

Explanations are discussions of concepts. Think "Food and Cooking, an encyclopedia of kitchen science"

  • Giving context
  • Explain why
  • Multiple examples, alternative approaches
  • Making connections
  • Neither an instruction nor a technical manual.

4. Reference: Information oriented

Reference guides are technical descriptions of the machinery and its operations. They explain classes, functions, methods, and are information oriented. They should list and explain things. While they may include examples, they should resemble more an encyclopedia article on an ingredient instead of a recipe.

  • They should mirror the structure of the code base, so that the
  • They need to be consistent with the code
  • They describe the code
  • They need to be accurate

Gotchas

Keep them strictly apart – if they mingle, things are hard to find. Be aware of the following similarities to keep them apart.

  • Practical steps in How-to guides and tutorials
  • Theoretical knowledge in explanations and refrerence
  • Tutorials and explanations are most useful when studying
  • Guides and references are most useful when coding

Programmers can learn much from pilots: keeping things properly separated (and also dressing better, and crashing less):

  • Tutorials are done with a teacher
  • How tos are studied
  • Reference contain only schematics and the such
  • Explanations are required to explain, y'know, why and how the plane stays up