Documentation is a key part and more often under-rated aspect of any product.
Documentation can be your best bet as a source of leads. From a marketing point of view, it can attract potential investors and customers. From a technical point of view, it can attract talent. Documentation is also a wonderful way to create a community around your product or service.
I am by no means an expert in writing good documentation, but I have been working hard to figure this thing out, and I am trying to put what here what it works for me:
-
Start describing what problem is trying to solve your product or service. Make it clear how your product or service fits into the consumers' lifestyle in some way.
-
Good documentation requires clarity. I tend to start with a declarative statement about the concept I'm writing about. This usually can be structured as
[thing] is [description of thing]where description is actually a description. -
When documenting a feature, try to know how you want the user to use that functionality, and then describe the process to do that. If there are multiple ways or scenarios, make that clear, but you should provide a reference for when they're first getting started. Get them hooked as quickly as possible.
-
Not everything has to be included at every stage of your docs, but everything should be documented for users who want more information or want to dive deeper. Undocumented features or exceptions can lead to frustration and become a time suck as users. Don't hesitate to add more information whenever it's needed.
-
Examples are better than words. Aim to provide as much real-world examples as possible. Different examples for different scenarios. Too many examples are not enough. And make sure they apply to the concept you are documenting, and of course, that they don't introduce new concepts.
-
Try to know your audience. Listen to feedback, it's one of the most effective ways to determine if your documentation can be understood by others. Of course, feedback is a continuous process, you should monitor the troubles your users face. But remember, we are all different, with different needs and expectations, and your job is to make the thing accessible to as many people as possible.
-
Effective documentation is kept up-to-date. Your documentation should be a living thing and changing, at same pace like the product. This is surprisingly challenging. This includes new features, but also rewording to make the docs easier to read and understand.
-
This is controversial but try to collect metrics on how the documentation it's used, how a user interacts with the content, what seems to be more useful and what isn't. This data will help you to prioritize what needs a rewording.
-
Involve your audience. Open a public edition workflow so anyone can contribute and improve to the documentation. Create guidelines and a style guide to give consistency to the content. The simplest way to make documentation easy to contribute to is to treat it as code, storing it as text in source control.
In conclusion, documentation is a living product and has the same needs as any other product: metrics, user testing, QA, workflows... I hope these guidelines are useful as you draft your project’s documentation.