Documentation minifesto

Thinking about documentation efforts, I came up with these principles:

  • Engineers should explain their work
  • There’s a right amount of words, and it’s probably more than you thought
  • Don’t let the perfect be the enemy of the good
  • Fixing existing words is good
  • Words need to be tailored to audiences
  • There are different kinds of docs:
  • Put words as close to code as possible
  • Use tooling to make words easier to find
  • Reduce duplication
  • Linking is fine



Regarding different types of docs and how we can sustainably maintain them, we’ve considered this and put in a recommendation in our Developer Docs OEP. We can update the OEP if folks have a desire to merge it with other ideas from the divio blogpost.

Other considerations, like co-location with code and aspects of tooling are also in the OEP. It would be great to amend the OEP with further principles as you have here that we think are useful.