Building a strong documentation culture

Documentation is often a dreaded word in most teams and organisations. The D-word is often associated with negative experiences like overhead, bureaucracy, processes, burden, etc. A part of the reason for this is the lack of guidelines or clarity around the purpose, scope and value of documentation. In other words, lack of a strong documentation culture. However, documentation done right can supercharge productivity and output of teams and organisations. For remote or hybird teams, a good documentation culture can boost productivity further. This article aims to clarify the why, what, when and how of documentation for primarily technical teams. The goal is to provide a set of guidelines for establishing a strong documentation culture aligned with the larger team/company goals and context.

Why document?

Humans forget: Days, weeks, months and years after taking decisions, making design choices etc. Documentation stores snapshots of our understanding and insights for the future which helps us recall key information.
Helps onboarding new team members: Reading documentation helps new members gain context, learn about the existing body of knowledge in an efficient and self-serve manner.
Prevents information silos: As projects mature, project teams get structured and focused, information tends to get siloed. Documentation spreads the knowledge across the organization and helps teams and individuals understand what’s going on in the organization, how the work of others impacts their own work and vice versa.
Knowledge capture and reinforcement: If you learn something new, the best way to improve your own understanding is to teach it. The second best way is to write about it.

What to document?

Development processes: Processes that cannot be automated and require manually running steps to build, install, provision, tweak etc. These should be well documented for junior engineers or those unfamiliar with the details of the system to be productive.
Architecture, Interfaces and Design documents: System and software architecture, interface specifications, design specs etc.
Working with external or third-party tools: If you use external libraries/tools/software/systems in development, it is helpful to document practical information around usage that helps the team and wider org using the same tools to get up to speed quickly.
Research findings and analysis: If you have done some study or research on a topic, summarize your findings in a page. This helps you crystallize what you’ve learnt and also for others to get involved, comment, collaborate or pick up where you left off.

There are several other processes and artefacts that can be documented in a team or an org:

Architecture (System, sub-system, unit, SW/HW)
Interface specifications between systems, sub-systems etc.
Development processes (running code, writing code, reviewing code, getting something to work)
Algorithm evaluation results
Own research results/summaries
Literature reviews

When to document?

As you go: Documenting as you go is the best way to ensure that you capture the most important information. This is especially true for research findings, analysis, design decisions, etc. that are fresh in your mind.
Before you go: Documenting before you go is a great way to get alignment on complex or high value work or decisions that need signoff from others. Typical examples are design documents, interface specifications, RFCs etc. that need to be reviewed and approved by others.
After you go: Documenting after you go is a great way to capture learnings from a project or a task. This is especially true for lessons learnt, post-mortems, retrospectives etc. that are done after a project is completed.

How to document?

A company wide knowledge management tool like Notion or Confluence is a great place to start. These tools provide a rich set of features to create, organize and share documentation. They also provide a great way to collaborate on documentation. However, these tools can be overkill for small teams or projects. In such cases, a simple markdown file in a git repo (for engineers) or a shared Google doc can be the quickest way to start. The key is to start documenting and then iterate on the process and tools as the team grows and matures.

Creating a documentation culture

Lead by example: The best way to get others to document is to lead by example. Document your own work and share it with others. This will encourage others to do the same.
Make it a habit: Documenting should be a habit. It should be a part of the process of doing work. It should not be an afterthought or a chore.
Make it easy: Documentation should be easy to do. It should not be a burden or a chore. It should be a natural part of the process of doing work.
Make it visible: Documentation should be visible to others. It should not be hidden away in a private folder or a private repo. It should be shared with others and made accessible to others.
Make it collaborative: Documentation should be collaborative. It should not be a one-way street. It should be a two-way street where others can comment, suggest, edit, improve, etc.
Make it a part of the process: Documentation should be a part of the process of doing work where applicable. For engineers, this means documenting code and development processes where necessary. Exercising judgement is important here as over-documenting can be as bad as under-documenting.

Conclusion

Documentation is a key enabler of productivity and output in any organisation. It does this by enabling knowledge sharing and collaboration. Every high performing team or organization will have an effective documentation culture. The guidelines in this article can help you create an effective documentation culture in your team or organization.