How should product managers write documentation? Conveying the right message - News

[ How should product managers write documentation? Conveying the right message ]

Most of the open source projects do not get enough eyeballs just because the authors are not really interested in, capable of, or don’t have time to build a good documentation environment for their API and product documents. However, it doesn’t matter how good your software is, because if the documentation is not good enough, people will not use it. Even if for some reason they have to use it because they have no choice, without good documentation, they won’t use it effectively or the way you’d like them to. Understanding how to write good documentation takes a lot of time and reading other projects’ documents from time to time. But take my word for this as I have written tons of documents at Countly — if you are writing code that will be used by someone other than yourself and especially if those people are your clients, your product should be documented fully. “The goal of documentation is to turn novices into experts,” says programmer and blogger Steve Losh. “Think of your documentation as a lesson (or series of lessons), because that’s what it is.” What is the difference between tutorial, how-to, explanation and reference? Many people tend to think that those 4 terms coin the same thing. However, they convey different meanings. As per Divio, those 4 terms can be explained as follows: Writing API documentation, writing product documentation or writing code documentation are different things. Clickhelp defines several documentation types, mentioned below: In this blog post we’ll focus on product (feature) documentation, especially in public facing open source projects. We hope that after reading this post, you will be able to decrease support requests, get better ratings from your clients and better, 5-star reviews from tech publications. Let’s start. Reasons to write good documentation Before moving forward, it is necessary to understand why good documentation writing is a quite important but underestimated necessity in today’s world. Especially in open source projects where almost every activity is open to the public and where such activities play a critical role in project’s success, detailed and well written documentation is one of the key factors towards mass adoption. Let’s look at the main reasons to write good documentation. 1. It provides better onboarding for your clients Exposing your clients to good documentation related to your product will help your clients feel safe, making them feel like they are at home, guarded and secure. In order for this to happen, you must a) make sure your product documents are visible and easily reachable, either via in-app links or under a searchable documentation platform, and b) make sure they are well written and help guide the customer find their answer easily. One tip here is, just write your document only once and it will be consumed over and over as your customers onboard. 2. It results in less support requests Good documentation helps customers understand how your product works. If they cannot figure something out, it is really frustrating and customers start to blame your product instead. If there is a roadblock, some users immediately call or email support team — but if the documentation is shiny, available and understandable, then they will fix their own problems, without consulting you, which in turn make them feel empowered. 3. It supports your own team A good knowledgebase can support your own team as well — as per Freshdesk, “a knowledge base is the one thing that can be instantly useful for both your support agents and customers equally”. Hence, your internal team should be aware of features, upcoming roadmap, API documentation and everything that is required to keep everyone on the same page. Step by step suggestions to writing good documentation Writing the document content and structuring this task is a bit different than what tone to use, and how to make sure your documentation is clear. As per O’Reilly, there are 8 rules of good documentation: Write documentation that is inviting Write documentation that is comprehensive, detailing all aspects of the project Write documentation that is skimmable Write documentation that offers examples of how to use the software Write documentation that has repetition, when useful Write documentation that is up-to-date Write documentation that is easy to contribute to Write documentation that is easy to find Those items mainly deal with the content. We are now going to dive into “how” to structure this content in 6 steps: 1. Decide what you should document Before diving into documentation, first get an understanding of what kind of documentation you are writing: is it a tutorial, a reference, a how-to or an explanation? Keep in mind that the nature of your product will directly affect the type of documentation you will work on. 2. Make a structure Build a structure first — this can be something very small at the beginning, and can include a few groups but as time passes, the whole platform you are building on starts to scale. From time to time, you should revisit your structure. Do not forget that you are the teacher and you are responsible for how your students will learn. They will be guided with your instructions, hence the more time you spend in structure, the more successful your students will be. 3. Always use good multimedia practices Make sure you benefit from videos, illustrations and various designs — they not only help users understand the message you convey better, but also provide a good SEO — you will get tons of quality leads from your images too. 4. Make sure it is searchable The search capabilities of different knowledgebase platforms vary — some of them just have plain search where you cannot deep dive into segmentations (which is technically perfect if you don’t have thousands of files), and some provide query options where you can search not only in docs but also in usernames as well. But one thing matters: you should be using a tool which has a fast search capability. An in-app search mechanism helps you search in files, plus see a preview of them easily. 5. Always improve and update The biggest hurdle with documents is their journey — they are created, used and then forgotten — never updated by the people who have created or benefited from them. As time passes by, the folder structure acts like a grave since older documents tend to stay in a lower position down the monitor. Hence, make sure to revisit your old documents, improve them and encourage your employees from time to time to do the same. 6. Write more than documentation It is always as important as being good at different things makes you a better person in general, and this is also true for documentation. As Joel Spolsky says, “If you need to write specs and you can’t, start a journal, create a [blog], take a creative writing class, or just write a nice letter to every relative and college roommate you’ve blown off for the last 4 years. Anything that involves putting words down on paper will improve your spec writing skills.” That is a great point — the most successful people around are those who can express themselves best, or who can explain what they can do best. And that can only be done with proper writing capabilities. Final bits Do you want to learn more about writing good documentation? There are several great resources, series and knowledgebase articles for software documentation experts. — Görkem Çetin @ Countly