Writing to Make Things Real: How to get people to value documentation

If you wish that your organization did an amazing job at documenting important things but don't know how then this 10 minute article is for you. It covers what is good documentation, who is responsible for it, and how to get people to care about it. If it is useful then share it, post it, and send it to others. The world needs better documentation!

Getting a single person to document a single thing as part of their job can be hard. Getting the people of an organization to pride themselves in how well they document things may seem like a beautiful if utterly impossible fever dream. But we at Urban Dynamics pride ourselves in doing things the right way both internally and for our clients, which is why documentation is one of our core company values. It's also something we've helped companies across many industries raise the bar on just by working with us on various projects and seeing what doing documentation well actually looks like.

But what is good documentation? Who is responsible for it? And how do you get a large group of people to do it? This article covers all this and more, starting with what is good documentation.

What is Good Documentation ​

"Quality means doing it right when no one is looking." — Henry Ford

Good documentation is like a good salesperson. The best sales people are so good you don't even realize they're sales people. They lack the "sales-ness" that we all think of with a telemarketer or used car lot associate. Documentation is no different. Ideally, it should not feel like "documentation" in the way that your car owner's manual in your glove box probably feels like documentation, especially when you yell at the inanimate object that it is whilst broken down on the side of the road.

There are a few key things that let documentation escape the "poorly written car owner manual" category. At a high level, these are:

1. People know about it and can easily find it. You may laugh at this, but you would be amazed at the number of times decent documentation existed and no one knew about it and thus no one ever used it. The car owner's manual cannot help you if you don't know it exists. So if you have documentation, people should know it exists, be able to find it, and be able to find what they're looking for in it.
2. It understands its target audience and meets them where they are. You know how in your car owner's manual under "How to change your tire" it says things like "Retrieve the hand jack from its hidden compartment and place it under one of the intended metal contact points on your vehicle’s frame" and you have no idea what any of that means or what a hand jack is or why they've hidden it from you in this moment of dire need. The documentation failed to know its audience (non-car-enthusiast) and meet them where they are (broken down on the side of the road).
3. It contains both the knowledge and wisdom the reader needs. Knowledge is information, separate from "us" as people. Wisdom is contextual to "us" as people. Knowledge is what a hand jack is and where your car company hid it from you. Wisdom is understanding how to use a hand jack to lift one side of your car up and if you try to use it in mud then the earth will eat your hand jack and you will be sad.
4. It is enjoyable. This is an aesthetic point and therefore much more subjective. But generally, the goal is for people to have a positive experience with it so they will use it again and ask others to. For example, has this article been enjoyable for you? Have you chuckled, grinned, nodded, and empathized with the slightly absurd examples of having a flat tire? Would you recommend this to someone else? If we've done our job right, the answer to all of these is yes!

Who is Responsible for Documentation ​

"Doing anything well looks effortless. It also takes a humongous amount of effort." — Ferris Ellis

Documentation is a series of systems, of practices, of SOPs (standard operating procedures), of things we all know we need but so few actually do. As such we need to think about responsibilities at two levels: (1) who's responsible for the system and (2) who's responsible for following the system. Both are key but, in our experience it is the first that is often overlooked. So let's start there.

You need a documentation owner. Whether your scope of responsibility is a team, department, business unit, or entire company, you need a designated person who is responsible for the Documentation Systems (we made it a proper noun because it's important) at their level. Depending on your scope of responsibility that person may be responsible for Documentation Systems across the entire company or a single team. We'll get to what they do in a second but the most important thing is that their main job is documentation and they have the highest quality standard for it of anyone doing documentation. If they are (1) spending most of their time doing not-documentation-things or (2) have a low quality standard for documentation then they will not be effective at their job.

With that out of the way, this person does a few things:

1. Own Documentation Standards: Ensure there are clear standards for what gets documented, where it gets documented, who owns it, how it evolves with time, and the tools used to do this. These are your Documentation Systems. This should, of course, be documented by them. If they're at the top of the company then they create these systems at a high level. If they're not then they're taking the broader practices and systems from those above them (which hopefully exist) to expand, adapt, and implement to their specific team, department, etc.
2. Train People on Documentation: This means teaching people both the Documentation Systems and how to write documentation. Remember that writing is a skill and just like all other skills we are born without it. You don't have people who are "bad" at documentation, you have people who are "unskilled" at documentation.
3. Spearhead Key Documentation Efforts: Creating documentation for something can be broken into two categories: (1) following an existing pattern and (2) creating a new pattern. When you need to create a "new pattern" for documentation, such as documenting a new type of process for the first time, you probably want your head documentation person involved because that first document will serve as the reference point for similar documents in the future.
4. Enforce Quality Assurance on Documentation: All documentation should go through QA. At a minimum QA should involve two experts: one for context specific knowledge and one for documentation in general. The person most qualified for the context specific knowledge is a subject matter expert while the one most qualified for documentation in general is probably your documentation owner. They should not necessarily review everything as that may be more than their bandwidth but new documents, major revisions, etc. should certainly involve them.

That was a lot, but we now get to move on to what everyone else does with documentation. Thankfully this is a shorter list:

1. Be Trained: Sounds obvious, but you make it a priority for people to be trained in the world of documentation. Research has shown that people tend to be bad at things they have no training for. So you should have a way everyone is taught the technical writing skills expected of them along with the Documentation Systems mentioned above.
2. Make Documentation Part of Their Workflow: Documentation should never be an afterthought. It should be part of every deliverable and a mandatory item on the "Definition of Done" checklist. Adding a feature to some software? Have to add documentation. Changing the manufacturing process? Have to add documentation. Designing a new product? Have to add documentation. Improving the guest check-in process? You guessed it, have to add documentation.

How to Make People Care About Documentation ​

"We write to make it real. If it's not written down, it's not real." — Urban Dynamics mantra on documentation

Here's the real secret sauce. You can do everything above but if your people don't care or think anyone will read there documentation then they won't buy in and then there will be a mutiny and then you'll always complain about "Why is the rum gon-", oh, sorry, wrong plot line. Anyway, the point is that people caring is important! Without it, you will not reach your documentation dreams.

There are a few key points we've found for getting people to buy into documentation as a value. Your mileage may vary, but this should serve as a good starting point:

1. Have a Mantra. It sounds lame, but having a clear simple message you can repeat over and over again will sink into people's heads. At Urban Dynamics, ours is "We write to make it real. If it's not written down, it's not real." If someone should have updated documentation but forgot then they'll get a polite reminder accompanied by this phrase. Don't overuse it, you don't want people to get sick of it. But it should be something you have no doubt anyone who's worked there a while can recite easily.
2. Connect with Existing Values. People are generally hesitant to change, so to make change more agreeable we connect it with things they already value. This is the core concept behind branding but that's a whole lot of psychology we'll skip over for now. The point is if you want dog lovers to buy your shirts then you sell shirts with dog stuff on them. If you want your "agile" team to do documentation you sell them on "agile documentation". You get the idea.
3. Lead By Example. No one likes being left behind. Be the innovator that starts doing documentation with quality and place your focus on converting the early adopters. The early adopters will convert the early majority, then they in turn will convert the late majority, and finally, the laggards will convert. This is how the Technology Adoption Life Cycle works and we think this applies to documentation too.
4. Highlight Pain Points. Remember that time at work when everything went wrong and you had to stay at the office until 2am while getting yelled at because you couldn't fix the thing and the documentation for it was bad and outdated and you missed your own birthday party? Do you want that to never happen again? Then you probably feel very motivated to spend effort making documentation better. We all wish human psychology was better at anticipatory regret but, for most people, it is not and thus this is the main learning feedback loop.

Conclusion ​

You made it to the end! We covered what exactly good documentation is, who is responsible for it, and how to make people care about it — all in under 10 minutes. If you found this useful then share it, post it, and send it to others. The world needs better documentation.

If you want to go deeper on this topic there is still plenty more to learn. What is covered here is just the beginning. There are more advanced discussions to be had around tooling, rollout, communication, etc. plus how to handle specific situations that may arise such as compliance, centralization, access control, and avoiding staleness. If these topics interest you and you want us to write more about them or talk to us about them you can do that here.

Thanks and hope this helps make documentation better for your life and those you work with!

Additional Reading ​

Oh, you're still here? You want to read more things? Here's a few links that we find helpful in the work we do in software. They are all free and publicly accessible.

1. The Software Documentation Guide by Write The Docs: Want to see a premade guide that offers a sane and extensive baseline for documentation in software? Then this is the link for you: https://www.writethedocs.org/guide/
2. Excerpts from Software Engineering At Google: Are you a software engineer and want to learn more about what documentation looks like in your job role? There are some excellent chapters from the O'Reilly book Software Engineering At Google that cover this. We'd particularly recommend this section from "Chapter 3: Knowledge Sharing" and all of "Chapter 10: Documentation".