Establishing a Documentation Culture

Build a culture of documentation to improve collaboration in your distributed team.

Successful distributed teams make documentation a priority. Documentation works 24/7, in every region and time zone. It supports asynchronous collaboration, creates a historical record of important decisions, and helps team members quickly get answers to common questions.

In my previous post about remote and flexible work practices, I wrote about my own experience with documentation-centric collaboration. But how do you establish a documentation culture? How do you convince your team to embrace documentation in their daily work?

For this post, I thought I’d do something a bit different, and share some bite-sized suggestions for how to bootstrap and nurture a culture of documentation in your organization. These are all things I’ve tried with my teams, and found to be effective.

Here we go…

Create an employee manual and onboarding guide in your documentation system. This helps new employees get in the habit of looking at the documentation. And it creates a place that people will visit regularly to look up benefits, policies, and other employment-related content.

When someone asks you a question, document the answer, then respond with a link. This ensures it’s the last time you have to answer that question, and establishes a habit of looking at the documentation first. If you ask your team to follow the same principle, you quickly build up a library of fresh and relevant Q&A content.

Default to open. Whenever possible, make content available to anyone in the organization. You can’t predict who will discover your documentation and benefit from it — so why restrict your audience to just your own team or department? Plus, keeping things open creates an environment of transparency, accountability, and trust.

Highlight and celebrate examples of good documentation. You can show off great content in review meetings, weekly updates, or group chat channels. This shows you take documentation seriously, and creates a positive feedback loop for contributors.

Assume readers lack context. Don’t use jargon and acronyms without explaining them. Link to prerequisites, prior art, and other relevant documents. This makes your documentation friendlier and more accessible. It also makes it less daunting for new team members to contribute.

Include documentation in your career progression framework. As people move into more senior roles, it’s increasingly important they can clearly express ideas to their teams and leaders. By calling this out in the career progression framework, you create both an incentive and an expectation for everyone to actively improve their written communication skills.

Share your personal notes, unless they’re truly private. Most of us write things down to remember them for ourselves. But if you put in the extra effort to organize your notes and publish them, your whole team benefits. Plus, chances are this extra step helps you clarify your own thoughts, and retain the information better.

Create a public list of things that need to be documented. When you’re bootstrapping a documentation effort, people don’t always know where to start. If you share a wish list with the team, you may get help building out the content — and you quickly find out who likes to write.

Regularly delete out-of-date content. Stale content makes it harder to identify relevant information, and sends a message that the documentation isn’t actively maintained. This undermines your efforts to build a healthy documentation culture. One exception to this rule is any documentation you maintain for historical purposes, such as decision records.

Cover topics you want your team to care about. If you’re committed to improving something like diversity, make sure there’s documentation around it — such as guidelines for inclusive hiring practices. This is especially important if you’re a leader in your organization, because people consciously and subconsciously optimize for the things you focus on.

Document tactical and operational things, like project plans or coverage over holidays. This brings people into your documentation daily, and makes the content feel current and relevant. If possible, surface project status in your documentation as well, so stakeholders don’t have to dive into your task tracking tool to keep tabs on progress.

Create templates for interview notes, onboarding checklists, decision records, and other recurring content that should follow a specific format. Better still, create a quick link that generates a new document of the selected type, and populates the author, tags, and other metadata. This lowers the barrier of entry for creating structured documents, and encourages consistency.

Add a list of popular or recently edited pages to your documentation landing page. This gives new arrivals a way to sample the documentation contents, and helps everyone find documents the team is actively collaborating on. If you want to gamify your documentation with a bit of friendly competition, some documentation tools also let you add a list of the most prolific contributors.

Appoint an information architect to keep things clean and well organized. Low quality and poorly structured documentation turns people off. If you have the budget to hire a trained information architect, that’s amazing. But for everyone else, find someone in your team who cares deeply about documentation. You can ask them to spend a portion of their time organizing and maintaining your content. Perhaps they can also help evangelize your documentation culture, educate contributors, or create a house style guide. If you run a team and you have no takers, then congratulations, you’re it!

Good documentation is a superpower for distributed teams. Hopefully these ideas get you thinking about new ways to support the documentation culture in your organization. And if you had success with other approaches, I’d love to hear what worked for you.