Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment