Not too long ago I changed companies. I have been with that company for more than two years, and in that time you get to do a lot of things. In my case, I had played an important role in much of the code in my department and the decisions taken. Therefore, I should leave good documentation in the department for the people who took over from me.
But how do you make good documentation and, above all, how do you write useful documentation? As a result of this question, I read many articles and asked many colleagues in search of some enlightenment. This is the result of my research.
Who is it for?
First of all, it is important to know who you are writing documentation for. It is not the same to write it for a team that is already working on a project, for an end-user, or for someone new who has just joined.
In this article, I am going to focus on writing documentation for people who were previously outside the company, although many points can be used for other types of readers.
Initial explanation
The newcomer may not know anything about the project, so it is very advisable that there is an initial explanation of what the project does, how it works, and how far it goes.
In this first description, you can explain everything necessary to understand the platform: types of users and their permissions, all the products, and the different licenses... Everything necessary for someone who is completely out of context. As if you were telling your wonderful grandmother what you do for a living.
Installation and start-up guide
That new person who has just walked in has no idea where to start, so let's start with the most important thing: how to install your project. Describe step by step everything they need to do before they can install it. To enhance this explanation you can attach any commands and screenshots you see necessary.
Once you know how to do this, you need to know how you can get started, so the next step is to add a tutorial to get you moving. Along the same lines, documenting how deployments to production are done is paramount.
Tutorials
We have talked about writing tutorials for installing and starting the application, however, there will be other circumstances in which these are useful. Locate those situations or processes that would be easier with a step-by-step guide and write them down. Don't forget screenshots, any links that may be needed, and other useful materials...
Structure the content.
If you have a lot to tell... it's better to keep it tidy. Likely, people will not need to read your entire documentation all the time. There will be circumstances in which it is only necessary to consult part of it. So organise it properly so that the most important topics can be found easily. Similarly, give your content a hierarchy. This will also help people to find what they are looking for.
Libraries and methodologies
It is useful to centralise somewhere all the libraries and methodologies that are being used. In the case of the former, next to them it is convenient that you explain which version you are using and what specifically they are used for.
On the other hand, for the methodologies, it is valuable to include a link to it. Not everyone may be familiar with it. For example, if the decision was made to use Atomic Design, indicate where they can read more about it. If it is not an externally documented methodology, you should record it in this document as well.
Architecture and decisions
The living beings in our team are not inside our heads, so it is necessary to explain the architecture that is being used. It is also very important that we justify why certain things were done in one way or another, as this will prevent certain mistakes that have already been committed.
In the same line, it is convenient that you indicate decisions such as the nomenclature used for the variables, if spaces or tabs are used, the most used breakpoints...
Errors
If some errors or circumstances happen frequently, take special care to document them. Also pay attention to parts of the code that may lead to other problems if modified in a certain way, or to fragments of the application that may be tricky. The less time spent on these kinds of issues the better.
Use as much as necessary.
Understanding someone else's head is not easy, so use all the resources that help you make it easier: screenshots, links, commands, diagrams, code snippets (don't forget to include which files they are in),... It can even be useful to use as an example a PR in which you modified a certain part of a functionality or in which you fixed a certain bug, to illustrate why something was done that way.
Test your documentation
Identify as many audiences as you can and test your documentation with them. We tend to forget to mention key facts or knowledge that we assume that is obvious.
Document your own code
There is an often-used phrase that "code should stand on its own" and this is absolutely true. However, there will be situations where this is not so simple. For these situations: document, document, document.
Update
Your documentation might be fantastic, tidy, and has a lot of information. However, if it's not regularly updated it becomes useless.
FAQ
Add a Frequently Asked Questions section. Ask your colleagues their doubts about the project, the code, or problems they have met during the development and add them to this document. What is more, if someone requests your assistance more than twice for the same problem... It's time to add this issue to the FAQ section.
PRs are important
Make a list of PR or commits containing interesting or important discussions. This interactions may come in handy in the future.
Thanks Charles F. Munat, Jean-Michel and Nefario313 for some tips!.
Top comments (9)
I find writing documentaton very cathartic, and as someone who's get easily stressed by work I find writing documentation also helps me focus and get my thoughts and even my fears into perspective about a subject.
I once wrote a 450 page comprehensive system/app upgrade guide that was so well understood that 2 years later we found out that the app vendor's consultants were using my document "illegally" to organise and perform upgrades on all their client sites!
The one key for me when I'm wiring documentation is empathy, who am I writing this for and what's their base starting level.
I start all my documents with a declaration of what it's about, what it's *not * about and a small list of 3-5 techs you will be expected to know about, with links to other sources if you don't know them.
How long will the docs need to last ofr? Today, tomorrow, next month, next year, I've got documentation I wrote 15 years ago that's still in use.
As your English teacher taught you, "beginning, middle and end", which in tech docs should be an outline so you don't go off track and digress.
These are always my starting points.
I love writing and reading or reverse 🤣 and I love the chaotic situation when I need to focus on something that I can solved. Documentation it's like sex when is good, is very goood. When is bad is better then nothing.
And I forgot who telling me that words 🤔
Mia, that's a great article, I hope people read it and document better their thing. That's make such a difference when someone join the team for example. Reading is like telepathy.
My own tips for having more impact with documentation with less efforts
And documenting is useless if not updated regularly. It is a huge efforts maintaining the docs. Once outdated, becomes untrusted and unworthy.
I'm going to add this tip! Thanks
That's just like code.
Actually probably much less efforts than code, updating documentation is easy.
But yes, that's an important habit to have.
When someone asks me about something that's not yet in the documentation, either I update the documentation directly, or I give him the updated info and ask him to update the documentation.
I've just added your tips! Thanks
Good recommendations, but you missed the key one that everyone seems to miss:
Test your documentation!
Hopefully, no one writes code without testing it, even if only manually. And most devs have figured out now that UX means user testing – basing decisions on our own guesses is a terrible approach.
But for some reason we assume that we know instinctively, I guess, what those who read our documentation will need. That's absurd.
We should identify as many audiences as we can, prioritize them, and then test on subjects from each area. Don't assume anything.
I find this is a problem with most tutorials and teaching materials as well. I can't count the number of tutorials that have stymied me (an "expert" developer) because they forgot to mention some key fact or assumed knowledge I did not have. This has wasted literally hundreds of hours of my time ... maybe thousands over the years.
(Multiply by the number of readers to get an idea how much time and effort your failure to test your documentation has cost others.)
Test, test, test! You'll be shocked at what people take from documentation that you thought was obvious and straightforward.
That's true! I'm going to add that point