Skip to content

Instantly share code, notes, and snippets.

@jmewes jmewes/ Secret
Created Oct 12, 2018

What would you like to do?
What nobody tells you about documentation -- Divio blog


  • step-by-step guide
  • make sure that it is robust
  • Minimum explanation
  • Complete a little project

How-to Guides

  • How to a achieve a specific goal
  • Like a recipe to cook something
  • Series of steps
  • No explanation


  • background + context
  • goal: understanding of a certain aspect
  • different perspectives
  • the "why" of things: descision, constraints
  • alternatives
  • "Explanation should do things that the other parts of the documentation do not. It’s not the place of an explanation to instruct the user in how to do something. Nor should it provide technical describe."


  • accurate and complete
  • like an encyclopaedia
  • e.g. APIs
  • "austere and to the point"
  • Links to how-to guides, explanations and tutorials

This comment has been minimized.

Copy link
Owner Author

commented Oct 15, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.