No one reads documentation, at least no one enjoys reading documentation. You have probably observed this from your own personal experiences. You need to use a tool or library at work, you search for some term in your organization's knowledge base. If the steps are simple, you run them and if it all works, wonderful, the job's done. If not, after a few steps and running into issues, you ping the person/team that wrote the document and ask for help, because it's faster than trying to debug it yourself. But if you were the person on the other team and you are constantly getting pings for help, it's taking time away from the work you are supposed to be doing.
Now imagine this at an organization level. There are so many tools and moving parts and so many people using them. Any ineffeciencies multiple pretty quickly if your documentation is not clear or tedious to follow. Imagine 100 people wasting a couple of hours dealing with poor documentation, that's 200 human hours wasted. You can do a lot with a team of 4 people spending 50 hours on something. And the wastage continues until it's fixed or the tool is replaced. Outside your organization, if you are looking at a new tool or a product and you see that there are 10 steps to get started, your first impression is that this is not going to be easy and you start to imagine how much harder it would be to work with it in the future to get the job done.
Documents are great for
- Communicating ideas, having discussions and reaching consensus
- Reference manuals for all the minute details
- Recording rationales for decisions
Documents are not great for
- Instructions about procedures, especially critical ones
- Trainings
We are working in a time with so many apps, services and tools, and we have so many things to do all the time, that to pause and read some instructions, that amount of attention is reserved for something extremely critical. And if something is that critical, we should absolutely automate it and not rely on someone having read the documentation and followed it without making mistakes. I'm not suggesting that everything needs to be operationalized, but if you know that a document is going to be read by more than 10 people, then it's a good candidate to be operationalized. People time is the most precious resource in an organization and you need to keep that in mind when writing your next document. Most documents should have an automatic expiration time when they should be automatically deleted with few exceptions that I mention below. Here are some real world examples of what I mean by operationalizing documents
Example 1: Product onboarding
More people will try out your product, if they can just breeze through the sign up process, click through to provide the minimum information to get some value out of it, that can get the users hooked to explore the rest of the app and provide more information to unlock additional benefits
Example 2: API documentation
Writing a swagger spec and calling it done is not enough. The goal is to help others who are interested in your service to understand it's API and how to integrate with it. Build a sandbox, where someone can just go to a url and try out your API with some mock data.
Example 3: Code contribution guidelines
You can expect folks to read a readme and follow some contribution guidelines, but things like code style enforcement, merge request temapltes, codeowner notifications and approval requirements, setting up QA environments, release process should be completely automated or be able to run with one click.
Operationalizing your documentation or knowledge this way lowers the barrier for more people to try out your product or contribute to your ideas and projects. It creates a great first impression, saves you and your organization a ton of time in the long term and let's you scale and go after harder problems. You know you are doing it right, when you stop getting requests for help. It does not mean that you are not needed, it means that you are doing your job right.