Overhaul "importance of documentation" section

[edunham]

http://www.opsschool.org/en/latest/soft_skills_101.html#the-importance-of-documentation

Probably ought to discuss:

• Ops team vs company-wide vs customer-facing docs, and their different goals and audiences
• Tradeoffs between...
  • official/authoritative/approved vs up to date right now
  • persistent (wikis) vs ephemeral (irc logs)
  • controlling who has access vs avoiding redundancy (the hazards of mismatched versions)
  • pretty vs easy to edit
  • tribal knowledge vs written out
• pros and cons of automatically generated documentation (code, APIs)
• if nobody can find a doc, it effectively doesn't exist. Develop a system for finding the information you need when you need it, or it's useless. (anecdote: I've worked at a company where there search features of the multiple internal documentation sites got so bad we just used an irc bot plugin to search all of them. works pretty well actually.)
• If people find a doc that's wrong but looks like it should be correct, it's often worse than if they had no doc at all because it makes them think they don't need to ask questions. However, an obsolete doc that's clearly marked as obsolete is better than nothing because it can help people understand the problem and ask better questions ("what changed in how X, Y, and Z interact since $DATE?" vs "what's X do?")
• good rule of thumb for what to document: if you had to ask a coworker for a piece of information and it's likely to still be true the next time a team member doesn't know it (either via forgetting or being new to the team), document it in the place where you looked before asking them. If it's something that will change constantly, document how to get the information.
• Checklists for repetitive tasks that can't be scripted -- update the checklist every time you use it if you find any flaws
• "passive" vs "active" documentation -- once someone has used a document several times they might not look it up every future time they perform that tasks. If you update the doc to change how things should be done, notify the relevant people in a way that they'll notice (email, IRC, meetspace). Similarly don't spam people with notifications of irrelevant changes unless you want them to ignore you (though that's kind of already covered in the section on effective email)