documentation.md

Documentation

What triggers documentation?

• Processes/systems have a tendancy to go un-documented, sometimes for a long time, until some precipitating event causes a team to say "Hey, we should make sure this is documented"
  • Typically, this precipitating event is a key player either being on vacation or leaving
• Items that do get documented tend to be straightforward:
  • Dealing with events that happen with predictable regularity
  • Outlining the expected/trivial cases
• When teams start to worry about documentation, there's usually a focus on items that are less directly tangible:
  • "When you were troubleshooting X, how did you know to look here?"
    • The answer here is probably "gut instinct"
    • In many cases, that "gut" can be resolved into a repeatable process (although this is a tough mental exercise)
  • "If we wanted to expand Y functionality, where would we start?"
• One takeaway from this is that documentation is at its best when it is supplementing people, rather than supplanting them
  • Documentation is rarely a good substitute for hands-on experience
    • One goal - in addition to docs - can be to maximize the number of people who have worked on the item in question

Why do people not use documentation when it does exist?

(ordered highest lowest to highest)

• Document rot
  • Unmaintained and out-of-date docs cause confusion, and if encountered consistently enough, causes people to stop bothering
  • Possible remedies:
    • Set a regular review cycle for critical docs
    • (If possible) auto-flag docs older than a certain threshold as "needing review"
    • Make doc updates part of the release/change cycle, not counting an item as "DONE" until docs are done (pitfall here: many teams end up splitting docs into a separate work item, which is then continually de-prioritized)
• Collaborative culture
  • The best reason on this list - team members naturally want to help each other, and it's typically easier to ask the person who wrote the docs than it is to look up the answer
  • It's a good sign when the default response is not "RTFM"
  • Possible remedies:
    • "Sure, I'd love to help! Let's see if we can find the answer in this doc..."
    • Pairing to both find a solution and update the docs
• Inconsistent domain language (the bane of my existence)
  • Words are important - meaning, with this being a very technical line of work, we have specific words with specific meanings; humans (or, at least, Americans) sometimes have a tendancy to avoid using the same word over and over to avoid sounding "boring" (think back to college essays - "in your own words", "minimum word count", etc)
  • Unfortunately, this makes it more difficult to both write and find helpful documentation (otherwise, you'd need a search engine which literally reads your mind, and currently Google is the only one doing that)
  • Possible remedies:
    • Encourage consistency in language
    • Build glossaries
    • Use peer review to identify possible domain language inconsistencies

What about documentation tools?

• The only note here is specifically on Confluence - in an effort to let teams do everything with their tool, they've made it difficult to do anything
  • For an example, see this blog post, which demonstrates that managing a Confluence instance can be a full-time job
• Some suggestions:
  • Decide on a site structure
  • Be strategic about changes to that structure