Documentation manifesto

Working Groups Build-Test-Release
#1

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: https://www.divio.com/blog/documentation/
  • Put words as close to code as possible
  • Use tooling to make words easier to find
  • Reduce duplication
  • Linking is fine

Thoughts?

4 Likes
Documenting Open edX settings
Documentation strategy
#2

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.

#3

I like them. I would suggest adding:

  • Wrong words are bad - Some documentation written is just plain false, and it is anti-helpful. That being said…
  • Out-of-date words are better than 404s - As long as it’s clear that what I’m reading is out-of-date, I’d rather be able to read it than be faced with a 404
#4

I like the fact that you mentioned “reduce” and not “eliminate”. In documentation, as opposed to code, it’s sometimes better to to have some amount of duplication for the sake of clarity.