- 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?"
- "When you were troubleshooting X, how did you know to look here?"
- 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
- Documentation is rarely a good substitute for hands-on experience
(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
- 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