Mía SalazarNot 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!.
