When we start to try a new tool, library or framework, what will we first look for? Document!
When we are implementing a feature and forget how, what will we look for help? Document!
When different fellows enquiry similar questions and we don't have time to hang around with them, what can we offer them as an alternative? Document!
Yes, document plays a vital role in our life as a developer. However, writing a document is not an easy job. If the document is not good enough, it may shut our potential users out of the door and bring more hassle to us.
Several years ago, I created a little formatting library which was widely used in the following years. However, instead of enjoying the happiness of the success, I did suffer from my poor document (as I mentioned in "Writing library is not cool at all") until I received very helpful suggestions from a peer.
Thanks to the poor document, I have to deal with my daily job while hanging on the internal chat app to support my precious users. Their questions mainly were like "How to format xxx?" as if they had never spent time reading my document. But, did they?
Yes, they did read. There is nothing wrong with our users. When this happens, it must be the document is not doing its job well.
The structure of a proper document
Like writing anything else, documents require a clear and user-friendly structure to help new or existing users find the information they want.
You may get some clues from those popular libraries, tools or frameworks.
The rough document structure of React:
- Key features;
- A list of all the tools can help new users start their journey;
- A getting started tutorial;
- Guides for common usages;
- Advanced usage guides, including a testing guide;
- API reference;
- Contribution guide;
- FAQ.
The rough document structure of Lodash:
- A getting started guide;
- Why Lodash;
- API reference;
- Advanced guide for FP;
- Related links, including contribution guide, etc.
The rough document structure of Vite:
- Key features;
- Why Vite;
- A getting started guide;
- Guides for common usages;
- Similiar tool comparisons;
- Migration guide;
- API reference, config and plugin details;
- Related links.
We may find some patterns in these documents:
- There is an attractive landing which is full of why new users should try this product. If similar competitive products are available in the market, compare and show the advantages.
- Followed by a neat and simple getting started guide to try the significant features without knowing many backgrounds.
- Then, another set of guides to explain the common usages.
- And probably a set of advanced guides folding the complex, less applied use cases.
- Finally, a searchable place to list all the API details.
- Do not forget the contribution guide if you are looking for contributors.
- Also, a migration guide if there are multiple major versions.
The getting started guide
Once potential users are attracted by our fantastic landing or others (advertisements, user recommendations, etc.), the getting started guide is the key to open the door to a product.
Remember, a getting started guide ought to be as simple as no brainer. Users follow the steps, and they will get an express tour of the significant features.
It simply starts with an installation command with npm/yarn/pnpm or some script tags with the latest CDN links.
Next, it presents the command to scaffold a new app if the product setup contains multiple steps.
Lastly, it offers a minimal working example in just few lines of code.
Common usage guides and advance guides
A robust product may support various use cases that will confuse new users if we list them together. Therefore, it would be better to group the guides into 2 groups: one for common usages, the other for complex usages, and less applied usages. And place the common usage guides below the getting started guide for users who want to learn more.
In comparison to the getting started guide, these guides shall be a bit juicier. By slipping in context little by little between the steps, we may gradually demonstrate the concept of this product.
Furthermore, we may help users sort the guides from what they may require first and next, naming the guide with a minimal title containing keywords.
API reference
Apart from the guides, API reference is essential for all the libraries, frameworks and tools opening for custom integrations. It is meant for experienced users to find in-depth information as fast as possible. As a result, the APIs must be searchable in specific ways, such as Ctrl + F or a built-in search engine.
To keep the document up to date and minimize the effort for maintenance, I suggest generating the API reference from the code comments (e.g., like JSDoc). Since the comments live closely with the code, developers tend to forget less about updating the document while updating the API.
There are multiple choices for document generating in the market: Storybook, TypeDoc, JSDoc 3, etc. Finding one that fits your project and takes time to learn is definitely worth your effort!
However, a generating tool still requires extra input other than the source code. A description sentence for the constants, functions, classes, etc. and their parameters, properties, and returns would make the document more understandable. It is even better if we provide one or two code examples.
Contribution guide
If we would like to attract some contributions, a comprehensive contribution guide is necessary. It should include:
- How to set up the project from scratch?
- How to run the project from local?
- How to test the project?
- What is the process of fixing a bug and developing a new feature?
- Is there any other ways to contribute? Like providing suggestions and filing bugs.
- How to communicate with the maintenance team?
Additionally, it would be better to provide clues on where to start with the different kinds of tasks for large projects. Here are some great examples:
Write the understandable content
With a clear structure ready, we have accomplished half of the job. The other half, however, could be tedious yet crucial.
Just like how we alter our code to optimize its readability, a remarkable document craves our patience to modify words and sentences, even formats, over and over. There is no universal standard but a few well-accepted rules. And here is a great learning resource from Google to recommend: https://t.co/ioo5hnHMSX.
Except for the wording, it is worthy of mentioning context and repetition.
No matter how good is a writing expression, people get confused without sufficient context. As a result, we usually suggest avoiding acronyms and other unfamous terms. If we cannot escape the shortened expressions, we may insert links in our document to help. Read more about "Why Is Context Important in Writing?" here: https://www.masterclass.com/articles/why-is-context-important-in-writing#4-types-of-context-in-writing.
And repeat. As a developer, we hate repeating, almost like having OCD. It is about the golden rule - reusability in programming but not the one in writing. To enhance the understandability of the document, we shall repeat some explanations anytime, anywhere, if it is necessary.
Improve continuously
Last but not least, a document needs our care along with the application. If this version does not work well, we shall seek feedback and suggestions to improve it.
Though the effort of maintenance is often hidden, it brings us benefits the other way around, like attracting more users for our creations and avoiding trapping ourselves in the supporting chats, contributing to personal branding, soft skill improvements, etc.
Top comments (1)
You might be interested in reading the Diataxis site: diataxis.fr/. It breaks out documentation into 4 quadrents:
with the goals of each type. It also is used by documentation.divio.com/.