For me, writing documentation is almost like coming back to the roots. If you have played some video games, you might be familiar with the concept of throwing an advanced player into a new environment where the player has to start from the beginning (permanently or temporarily). In Assassins Creed Valhalla for example, after about 50 hours of playing I went to another location that basically resets your equipment to the basic one (which was an interesting challenge after collecting the best armour in the game) so you had to use your skills even more and start collecting equipment again. It felt really refreshing. And for me, it is the same with writing documentation.
Documentation by Developers
You dive deep into developing your product or project so you know it very well already. Taking a step back and positioning yourself as a regular user of your product will let you improve the usability, developer and user experience, and overall relations with the developers. Keep in mind that I do not try to convince you to be a full time documentation writer. I believe that dedicating some of your time for writing docs will make you a better developer in the long run.
Knowing exactly what problem you are trying to solve, how users are using the product, where they fail, etc will let you better solve problems. And this is what the developers are best at, Solving Problems.
Documentation for Developers
This is the perspective of developers writing docs but what about the other part, namely developers who are using the documentation? It is even more important! Educating users about your products is especially important if you want to have a community or clients.
Back in 2017, I remember starting to learn Vue.js and the official Vue docs were just great for that.
Year later, I tried Nuxt.js and was really amazed about the code examples that was solving majority of my issues.
Finally, in 2019, I started learning Nest.js and these docs were and are the best in my opinion.
The docs tell you how to build both simple and advanced applications really easily. Apart from written docs, there are several apps examples in the GitHub repository that you can take a look if you are struggling with some topics.
My experience with documentation
In my career, I wrote several documentation pages to both big and small projects. It is not a full time job for sure but spending few hours a week, writing tutorials and explaining the basic topics is a great way to understand the needs of your users better.
I started with rewriting the documentation of Storefront UI - Vue.js based UI library specifically for E-Commerce -> https://docs.storefrontui.io. It was built using Storybook so it is more like a playground documentation but it does its job well. I enjoyed explaining how every component work, how to integrate SFUI with Tailwind, Cloudinary, etc. Also, I thought about restructuring the docs so that they will address the current users issues at the first place. It was a great move that helped developers to know how to use Storefront UI properly.
After that, I wrote some documentation for Vue Storefront products and internal projects and found it especially interesting as I had to put myself in the shoes of the regular users.
Finally, I wrote several documentation websites related to Nuxt.js like https://algolia.nuxtjs.org/. I focus really much there on writing the tutorial step by step so that the users can easily start using it.
Summary
Writing documentation is great and you should try it out definitely. It will allow you to understand your users better. What's more, it will help you also solve your users issues before they actually experience them.
Top comments (8)
Different types of user require different documentation.
The person using your web API or your library needs to know "if I call this with these parameters this will happen" and also "to do this I need to call this with these parameters". These are two different views of the same information, of course, but found in different ways. I've found Stripe's online API doco to be an example of this done right, and exim's configuration doco to be an example of this done horribly horribly wrong.
In the mean time the person maintaining your code - whether that be you in a few months time or your colleagues - needs something different. They need a quickly accessible overview of the whole system and how everything interacts, what the private functions not exposed to the users do, where they are called from, how it is all tested, how it is deployed, and so on. For the overview I recently discovered PlantUML's sequence diagrams, which a colleague used for the overview of a system that talked to numerous third parties as well as talking to our other internal systems and having plenty of its own internal state. It beautifully summarised a year and a half of work in one simple diagram and was infinitely superior to the version I had produced earlier in a vector graphics package.
Don't forget to commit all your doco to version control, including the source code for diagrams, and to include pointers in doco/diagrams to code and vice versa so that you stand at least a small chance of keeping them in sync!
If you have the budget, hire a technical writer/librarian to help you make your documentation discoverable. All too often your company will have plenty of documentation written over a period of years which most people know exists but they have no idea how to find it because it was all written by individuals who thought they knew the perfect place to put it in your wiki, or it's attached to just whatever random ticket inspired its creation, or it's in the workspace of a team that broke up a decade ago.
Wow, this is a really detailed comment. Thank you for that! I think it adds another view on this subject and shows that documentation, while seems very simple, is indeed a difficult topic! I will encourage every viewer of this article to also dive deeper into the concept you mentioned π
What was so special about Nest documentation? π€
I would say that the documentnation has both easy and advanced examples that you can easily copy and paste to your project. It is almost like if we could have a documentation for Nuxt that will be merged from the current docs and all modules docs so that everything is in the one place. Also, the cat examples are just great!
Cats.
Valid enough reason. ππ»
Yes, these documentations are very well written. Check Angular's Documentation also. I love how it is designed and written.
I tried Angular few years ago, but I am more a Vue fan ;) But I will check it once again :)
No worries :)