Skip to content

Instantly share code, notes, and snippets.

@jmewes jmewes/notes.md Secret
Created Oct 12, 2018

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

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

Tutorials

  • 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

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."

Reference

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

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.