2020-02-25_bookclub.org

What nobody tells you about documentation

https://www.divio.com/blog/documentation/

Documentation makes your project more successful

• If your project is poorly documented
  • Folks won’t use your software
  • Folks will misuse your software, even if they’re forced to use it (see also rsync)

There is no 1 documentation: there are 4 things

• 4 types
  • Tutorials
  • How to
  • Discussion
  • Reference
• Each of these require a different style of writing
• All must be distinct
• All needed at different times
• Helps the author as well as the reader

Tutorials

• Rarely done well/most frequently missing
• What your project needs to show the beginner that they can do something meaningful
• Learning-oriented: enable another person to learn
• Analogy: Teaching a child to cook
  • Child finds it enjoyable/gains confidence
  • Wants to do it again
  • Through doing that child learns what’s important
• Learning a new craft or skill we learn by doing
• Inspire confidence in you and the tech
• Positions user to make sense of other docs
• Turns learners into a user
• Hard to produce and maintain
• MUST:
  • Be repeatable every time
  • Accomplish something “comprehensible”, however small; i.e., “Hello World”/Provide a sense of achievement
  • Concrete: deals with particulars not the general case
• DO NOT
  • Explain anything, it’s all about doing
  • Distract with options or choices

How to

• Take reader through steps to solve real-world problem
• Recipes: series of steps to follow
• Focus on a practical goal, steps to reach the end
• Address a specific question
• Good naming helps: i.e., titles matter – about the problem
• Different from tutorial
  • Problem-oriented: addresses a specific problem (vs learning-oriented)
  • Don’t need to start at the beginning
  • Flexible, not necessarily repeatable every time
  • Openness: reader can use it to get to slightly different place
  • User now has enough knowledge to ask a meaningful question (unlike with a tutorial)
• Same as tutorial
  • Practical usability is more valuable than completeness
  • Don’t explain anything – explinations get in the way of action

Reference

• Technical descriptions and how to operate it
• Information-oriented: list things, describe things
• May include examples, but no explain basic concepts
• Not how to complete common tasks
• Austere and to-the-point
• Food analogy: encyclopedia article about an incredient
• Same structure as the code-base
• Consistency with tone, structure, like a dictionary
• Other things tend to end up in the reference material

Explanation/Discussion/Background material

• Understanding-oriented
• Analogy: harold mcgee for cooking
• explain why things are the way they are:
  • design decisions
  • historial reasoning
• Contrary and conflicting opinions: make sense of a thing
• No instruction or technical description

Characterics of overlap between types

• Once one type bleeds into another the documentation gets worse
• There are inherit tensions that pull these types of docs together

Practical vs Theoretical

• Tutorials and How-tos
  • Both practical steps
• References and discussion/background
  • Both theoretical

Useful when coding vs Useful when trying to understand

• How tos and Reference
  • Useful when coding
• Tutorials and Discussions
  • Both useful when studying