Documentation Culture

   

I was talking last night with AT about documentation. A few of the points that came up seem like they could be a decent blueprint.

When To Bother

People generally understand that documentation can be valuable, so I won’t get into that. However, there are a few specific high-level properties that I think are worth pointing out:

In essence, documentation enables you to scale in some way. This could mean giving you more time, onboarding more people, transferring responsibilities, etc.

Documentation also has a cost—writing takes time. So, I’d argue that you should focus documentation efforts in areas that you want to scale.

The Challenge

I don’t think that writing is the real challenge when it comes to documentation. I think the real challenge is building a culture around documentation.

Consider: for documentation efforts to be successful, you need enough documentation that gets produced, enough documentation that gets consumed, and your body of knowledge has to be reasonably up-to-date.

The hard part there isn’t the act of writing. It’s the ongoing upkeep to keep things running. For that reason, you want a culture that values those activities—otherwise it will be a recurring pain to get them to happen. People can all write, it’s just that they can’t or don’t want to.

Strategies

Tackling this challenge will vary from group to group. These are some obstacles that I’d anticipate, as well as how I’d approach handling them.

Because the hard side of building a documentation culture is typically getting people to write, that’s what these strategies are focused on.

Organizational Resistance

Hopefully, your organization believes that documentation is valuable, even if they don’t actively make an effort towards it.

You want a champion who will push documentation efforts forward. Ideally, this is someone very influential whose domain of influence is your entire organization. If they care, they have lots of ways to encourage people to contribute.

If you don’t have this person, you unfortunately have to scale down. Find the most influential champion you can, and focus just on their domain. If you can’t find anyone, focus on you and your domain (even if your domain is just you).

When you have limited influence, your strategy shifts to be a grassroots campaign. Aim for two things: (1) write documentation that is useful within your domain and (2) share your documentation liberally when helpful.

Essentially, you’re stating that documentation is useful and you’re happy to reap the rewards from it. If and when others come around to it, you’re happy to help them get started and also benefit. (If you aren’t getting any return on your effort, you may need to revisit when to bother about documentation.)

Target Pain Points

The surface area that you could document is always going to be large. Instead, focus on what is most painful—the places where documentation gives more bang for your buck.

Some scenarios: - If someone is a gatekeeper of knowledge that is crucial within your domain, find ways to get that information out. - If your team gains lots of new members, focus on team-specific knowledge to help with onboarding. - If you want to raise the skill floor of your organization, focus on general-purpose basics.

In other words, your documentation effort should be more nuanced than “we will just write a lot.” Find places where documentation will pay off quickly—you’ll feel good about it and win over more people.

Minimize Activation Cost

If writing requires jumping through a lot of hoops, people won’t want to write. Make contributing as easy as possible.

Some things to consider: - Quality. Do you need top-notch writing? If not, settle for something simpler—in some scenarios, bullet points are perfectly viable. Generally, the more niche or less frequently used a resource is, the less effort you should spend to produce it. - Tooling. Is it easy to use your knowledge system? Is it easy to contribute? - Process. Simplify the checks and balances you have around contributing. Does someone have to sign off on a new resource? Can you relax your editorial/review process to focus just on key points, rather than nitpicks?

Strike While Hot

Think of your knowledge base as a cache. The value of a resource is based on how much it is accessed and how recently it’s accessed.

Just Ask

I consistently undervalue the act of asking someone else to write up some documentation. Sometimes it slips their mind. Other times they just need a bit of a nudge. Systems don’t change their behavior on their own—you need some kind of input.

It may help to clarify the scope of what you’re asking someone to write. It’s a lot easier to ask someone to jot down the key points than to write a fully thought out spec.

Pass The Torch

Find others who want to help with building a documentation culture. Encourage them and help them figure out what bodies of knowledge they can be responsible for. They might operate as a curator or as a writer.

By doing this, you’re creating little “documentation culture bubbles.” Hopefully, your collective efforts will help those bubbles expand and merge over time.

While you’re at it, help others’ efforts go further. If someone creates a resource, look out for appropriate places that you can share it (and credit them liberally). Even (especially?) when writing is painful, you want people to feel like their efforts are appreciated.

If you’re a leader, you can also influence just by showing that the effort is important to you. If you’re devoting time or interest, people around you will notice and do more of it. Even if it’s just a little bit, that’s another step in a good direction.