Don’t cheap out on proper documentation
TL;DR:
The reports released by Google and Microsoft state that documentation is extremely important and extremely glossed over in most IT projects. There is a host of reasons why you should take a closer look at the state of documentation in your organization. Documentation is critical because of its overarching impact on product contributors and product users.
Another example, for those too busy to read the whole thing, is GitHub’s annual State of the Octoverse (2021). The key takeaway from this report is that in both open source and proprietary projects developers see about a 50% productivity boost when documentation is written in a proper way and provides necessary information.
What’s interesting, the same report states that documentation is critical but often heavily under-invested.
Should I even bother?
We’ve all been there…assembling an IKEA wardrobe, learning a new programming framework, or building LEGO forces us to take a look at the documentation. We end up reading (or at least skim-reading) the manual to:
- discover product’s capabilities
- find an answer to your problem
- get a gist of what the product is without accessing it
- access the product itself (sometimes documentation is the product’s only interface — APIs and SDKs)
- to name a few
The above-mentioned reasons materialize user-centeredness. But what does this user-centered approach mean to a company that is building a product?
Well, it has a lot to do with product adoption, scalability, customer conversion, customer satisfaction, and ultimately money. In this blog post, I will present a value proposition behind documentation.
Productivity boost with documentation
If you’re like me, when you want to use a new product (framework/library) for the first time, you check the “get started” and tutorial sections to see how quickly you can start developing. But sometimes, there’s no documentation or documentation lacks guidance and is so poorly written that you just give up and look for alternatives.
Managers, product owners, recruiters, budget keepers, board of directors, decision-makers, take notes because your product will lose clients if you don’t take good care of documentation.
To back up my foreboding statement, I’ll refer to reports released by two giants in the software world, Microsoft and Google. Their reports have crucial findings relating to documentation.
GitHub’s annual State of the Octoverse (2021) report is organized into three threads, with one for creating documentation. The key takeaway from this report is that in both open source and proprietary projects, developers see about a 50% productivity boost when documentation is up-to-date, detailed, reliable, and comes in different formats (e.g. articles, videos, forums).
On my journeys through new products, I always feel well taken care of when I get to see pre-built examples and run them without installing anything (e.g.TensorFlow 2 quickstart for beginners), play around with the end-product interactively (e.g. CKEditor 5), or watch a video tutorial (e.g. Camtasia).
Another salient finding from the State of the Octoverse report is unsettling that documentation is critical but often under-invested. The excerpt from the report reads as follows:
In my experience, many start-up, small to midsize companies do not invest in creating professional documentation at all. Only when the growth of their product picks up the pace, they start thinking seriously about investing in the documentation. Contrary to smaller companies, technology giants and leading companies such as Google, Microsoft, Netflix, Facebook, and many more have a long-standing history of investing in the documentation.
They hire technical writers, professional information communicators who specialize in writing documentation.
The second annual report from the DevOps Research and Assessment (DORA) team at Google Cloud can be summarized as;
“Good documentation is foundational for successfully implementing DevOps capabilities.”
In the world of numbers, DORA’s research can be boiled down to the conclusion that teams with quality documentation are:
• 3.8 times more likely to implement security practices
• 2.4 times more likely to meet or exceed their reliability targets
• 3.5 times more likely to implement Site Reliability Engineering
(SRE) practices
• 2.5 times more likely to fully leverage the cloud
The report also has some battle-tested tips on how to improve your documentation. I encourage you to take a good look at it and apply them.
Writing a tech documentation is a group effort
Writing documentation doesn’t seem to be the most exhilarating job out there and is usually an after-thought; So, who usually wants to write it? Nobody, or a forced engineer who was tasked with the chore of writing words.
In that case, who should write documentation? Here comes a technical writer, a person solely dedicated to writing documentation or so the legend says. You will learn more about what technical writers do if you keep reading this post.
Actually, the responsibilities of technical writers are cross-functional in organizations, and writing documentation is only one piece in their remit.
Not to mince words, everyone in the organization should contribute to documentation- be it a product owner, architects, software developers, technical support, and your customer base. However, with this approach, the onus of responsibility for documentation is not clear-cut.
That is why companies need a person or a team (depending on the size of a project) who will champion and take responsibility for documentation… in a perfect world that someone would be a technical writer.
Sca, Scale, Scalebi, Scalability
Imagine if you were not able to watch a good tutorial on how to model a donut in Blender or create a virtual world with Unity and your only way to learn how to do this would be through interacting with the product and talking to others. A scary thought.
If you’re thinking about reaching a wider audience with your product, you need to have a strategy in mind. Having an open-source or SaaS product requires more scalable solutions than classical tech support. In fact, the notions of technical writing and tech support should be married in each company that is thinking about scaling their product. A well-written document can help solve the problems of tens, hundreds, thousands of users simultaneously whereas one tech support agent can typically attend to one problem at a time. The married idea of the two should manifest itself in creating a knowledge base, documents that solve specific users’ problems and the agents linking to a document as a solution. These days, more and more companies leverage chatbots to triage the incoming requests from users and offer a solution in the chat.
Happy users, happy life
Tutorials, in-app tutorials, self-paced educational materials facilitate learning about a new product and decrease the learning curve. Products should make use of documentation to provide footholds for users and modern documentation should leverage the wonders of guided paths for users who start their journey with the product.
Very complex products with, what seems to be, an endless list of tools and options must take a user by the hand and lead the way. One of the ways to ease the pain of getting the product for the user is embedded help in the user interface. Adobe does it very well through in-app tutorials and referencing to documentation from the UI.
Through this practice, users never have to leave the UI in search of help. Another way to accommodate your customer base is to offer self-paced courses like Udemy, Codecademy, Coursera, Khan Academy, to name a few. Combining this form of help diversifies and enriches your documentation e.g. take a look at how ScyllaDB integrated these courses into their documentation. It is becoming a common practice to integrate such courses and call them {your product} University / Academy.
Conclusions
The arguments I showcased are only the tip of the iceberg and there is more to see than meets the eye for how important documentation in IT (and in general) is. Since the reports (not only the ones presented in this blog post) provide positive data-driven values for documentation, it is not enough to have documentation for your product, what’s more important is to have good documentation that scales and solves users’ problems. That is why you should invest in professional technical documentation.
Follow JIT Team, the human factor of IT
https://www.linkedin.com/company/jit-team
https://www.instagram.com/jit.team/
https://www.facebook.com/jit.team.poland/
https://dribbble.com/jitteam
