High Leverage Activities for Teams : Documentation

Documentation as a multiplier

One oft-repeated highlight of Amazon’s culture is the intense focus on excellent documentation. Several folks tout the high-quality docs for empowering engineers to self-service and figure things out. Alas, Amazon seems to be the exception rather than the norm – most teams have documentation woes and knowledge gaps.

Why is documentation essential?

The telephone game shows that the oral transmission of undocumented knowledge leads to warped facts. Eventually, multiple sources of truth emerge, and seekers get varied answers depending on whom they ask; this ambiguity will ultimately slow down the team and breed frustration.

The typical approach of establishing a trusted guardian or panel of experts is not a sustainable fix. The small cohort of experts eventually gets overwhelmed by the deluge of questions, asks, and requests.

Ironically, the willingness of these experts to answer questions, provide guidance, and help out is also the Achilles heel – that willingness accelerates the formation of bottlenecks. 

The experts unconsciously become gatekeepers – impeding asynchronous exploration and discovery by other team members. Furthermore, they also feel disheartened by the constant interruptions and demands on their time – a lose-lose situation.

Ask: is your team currently bottlenecked on the experts?

A more sustainable fix? Democratize documentation and instill a team culture of writing and reading.

Establishing a documentation culture

I always try to infuse a documentation ethos – whenever anyone learns something new, they write it down and share it with others. That way, the entire team’s knowledge span grows, and folks can unblock themselves instead of distracting colleagues with questions. 

How we solved our documentation woes on a newly-formed team

The highest leverage action for a newly-formed team I led was rapidly ramping up all the new hires in the new challenging domain.

The existing information might have well been in Njerep – it was esoteric folklore and known by a select few. As the team groped in the dark, we made painstaking efforts to document all discoveries. This practice seeded a resilient culture that thrived as the group became more proficient in the domain.

Once the culture was ingrained, the blind discovery strategy evolved into a spread strategy – owners got assigned to the various nooks and crannies of the domain and ensured docs were up-to-date.

Seeding a documentation culture

Based on the story above, here is a 5-step technique that might work for your team. 

1. Reconnoiter: Explore the space, understand what is needed, what is missing, and what needs to be covered. You can also rely on domain experts or folks with long tenure on the team to provide tips and suggestions or seed a broad topics repository for a knowledge base.
2. Distribute: Divide the topics amongst the folks on the team, ideally everyone (including you) gets some topics and is tasked with interviewing the experts, writing out their discoveries, and helping with getting things started.
3. Fix: Appropriately document discoveries, update outdated docs and delete stale docs. It helps to have documentation tasks included in the structured onboarding program; this act seeds a documentation ethos during the early team formation period.
4. Own: The documentation culture should be part of the team: The team should practice writing, testing, and sharing new docs.
5. Sustain: Consider setting up virtual teams or doc teams to help sustain the long-term health of the written docs. Documentation inevitably rots (just like software), so clear ownership and guidelines help. Some things I have seen work well include documentation quality tags, health checks, curation of content, etc. 

Testing documentation

I have found hallway testing very useful in unearthing knowledge bias and simplifying docs.

Recommendations for documentation

I prefer plain text (e.g. markdown, wikis) over specialized textual formats (e.g. OneNote pages, Word documents / Google docs, etc.). Enhanced formats require particular software, are difficult to search, and make serendipitous discovery harder. Thus, they go stale faster – generating a petri dish of unusable docs.

MermaidJS is an excellent markdown-based dialect for diagrams. It is extremely easy to use, try out the live editor for yourself.

The difference between insufficient and missing documentation

Poor documentation implies challenges with curating, sustaining, and maintaining healthy documents while missing documentation signifies challenges with creating valuable documents. These are two different challenges; the former means a writing culture already exists while the latter requires seeding a writing culture first (before embarking on the information architecture journey).

Wrong documentation indeed misleads; however, it is pretty easy to correct, update or even delete misleading docs. Orally transmitted anecdotes can be just as misleading; worse still, they are harder to fix.

Conclusion

Excellent documentation leads to efficiency gains, insufficient documentation leads to bottlenecks, while poor documentation sprouts confusion.

Investing in documentation pays off in the long run – there are fewer bottlenecks, peer teams can self-service, and onboarding new hires is cheaper.