The value of documentation and how to do it.
🇪🇸 First. Do you want to read this article in Spanish? Check it here.
There are millions of people working in their homes regardless of the current reality we are living. It is a new situation for those who are “obligated” to work in isolation without direct support from coworkers. In these moments, it’s when documenting processes and products are most necessary so that knowledge doesn’t only remain in one person’s head, but can instead be shared.
“We don’t have the time for that now. We are always improving the product, so documenting it has no sense right now”.
This is what you are probably going to hear when you say “let’s document,” which is not a task everybody likes doing and all teams tend to go towards chaos if there are no processes or clear leadership. It is when the PO/PM role can make a difference.
Documenting is never a waste of time.
Why documenting?
The human being is the only animal capable of tripping twice over the same stone.
Basically, to not fall twice over the same error and for future people who may enter the company not to find themselves into those issues. It’s not about taking pictures of the process or the product and frame it. Documenting has a palpable utility; it is a dynamic task that seeks the continuous improvement of the company. It allows us to know and understand it better, establish objectives, and lead the staff to the achievement of them.
During “word-of-mouth” formation, the relevant information is lost, which can affect the comprehension of the process and its efficiency. That also implies the transmission of defects and underwhelming results. In the new employee learning the wrong way ends up turning into “that’s the way they taught me” and that leads to “that’s the way it’s always been.”
Documentation allows registering your steps, so all the responsible ones involved know what, when, and how to do it.
“Time invested in documenting is saved time because every new person incorporated to the team will only need to read and assimilate documentation.”
In today’s world, everyone needs things to be done. There’s a lot of stuff competing for our attention: we (including our internal user: devs) need intuitive tasks. That’s why we need to document every product and process as a company, so our employees don’t need to put a lot of effort in adaptation, and thus, growing.
What is the objective?
Documentation consists of keeping a registry of a process during the execution of a project or task. The objective is to learn about the implementation to adapt strategies and improve the process.
Proactive and documented management of processes will:
- Eliminate mistakes
- Reduce time used on tasks
- Decrease costs of implementation and development
- Reduce resources related to tasks needed
- Improve efficiency
- Improve project quality
Documenting processes helps others to notice changes in behavior and necessary attitudes to produce desired results. It also brings context to operations, so others can see how the project fits in the big-picture and what the broad impact is.
Advantages and Disadvantages of documenting
Documenting is a cost we must bear as a company and developer, and this cost implies a series of positions (mid/long run) and disadvantages (short-run), which we must assume.
✅ Advantages
Documenting offers numerous benefits to your company, which makes an effort worth our time.
- Allows for timely changes to your company to increase productivity.
- The person who registers a process may not understand it completely.
- Improves security.
- Works as a learning tool at hand for new employees.
- It offers context for individual projects.
- Makes outsourcing easier
❌ Disadvantages
It’s a process that takes an impact on the employee’s time, and thus an economic cost, which has some “disadvantages” we may have to manage in time and form.
- The person who registers a process may not understand it completely.
- Groups of particular interest may use documenting of processes to generate problems.
- Documenting must be kept ongoing (otherwise it loses its utility).
- It is possible for big projects to contain a lot of documentation and thus get to the point of needing “documentarists” to maintain all documentation (and that requires an extra cost).
- Documenting can delay a project.
And we need to have in mind this last one.
“We need to look for the ideal time to start (the hardest) to document and generate this habit inside the company.”
Tools for documenting
There are multiple applications which we can use to record, and there is not a best or worst one, the team decides that. Those who adjust to the work needs we may have and our stack. Nonetheless, we must look at the long run. Is it scalable? Some of the tools are:
- Confluence
- Notion
- Google Docs
- Wordpress
- README (Yes, a simple readme in a repository is also documenting, this one’s for you, devs)
How to document?
Here’s THE question all projects have to go against (unless they have people with setup knowledge of documenting). Most importantly, having in mind what to document and its processes is a democracy in the beginning, and a dictatorship at the end. And I’ll explain.
It’s initially a democracy because everything is talked about and agreed upon. Thus it is open to change and continuous upgrade, as the project evolves (and grows on an employee level), we are “imposing” a way of documenting without wanting to. Changes must be approved and have a cost when applied, which is why I call it a dictatorship.
If the foundation of our documentation process is not reasonable, everything that follows won’t be useful as it could be. This is why it’s important to know how to document.
Not only you need to document, but also you must do it properly. A poorly redacted procedure can generate issues. Some of the most common issues when documenting are:
- Not explaining the motive or purpose of the task/process.
- Skip relevant information.
- Include unnecessary and distracting information.
Basic rules of documenting
From my experience, there are 9 Basic Rules for proper documentation; these are:
1. Writing attractive and clear documentation
The main important rule for documentation is to be the most beautiful it can. Which means we must try writing it in accurate terms, without skipping any steps. We must avoid making suppositions over what our partners may know. This sometimes may seem too much, and we may be tempted to say something like “all X developer knows about Y” but remember that each one of us brings our background and experience to a project.
It may result in a more detailed document, and lastly, it’s more straightforward because there’s less conjecture for developers on all experience levels.
2. Complete documentation, detailing all aspects of the project.
Must be comprehensive. It means all aspects of the project are documented. Characteristics or undocumented exceptions can lead to frustration, turning it into a waste of time because other users and other developers are obligated to read the code to find answers they need. Complete documenting of all characteristics eliminates this kind of ambiguity.
3. Writing easy-to-read documentation
We write skimmable documentation (quick to read), we help users to find the content they need quickly. Make records more comfortable to read. You can use clear headlines, ready with vignettes and links. For documenting large projects, a table of contents or more transparent navigation will help users jump directly to the information they need, rather than going through only one large document.
4. Offering examples is always a good idea
That includes models that allow developers to see how they can use the code themselves. The objective is to provide examples of the most common cases of use for the project, leaving the details to be covered in the comprehensive documentation.
5. Writing redundant documentation when useful
Perfectly acceptable include some amount of redundancy in documenting. When doing it, you recognize users may not be able to read complete documents or any relevant information in some parts of the documentation. While a right code may be DRY, good writing has an objective to be clear, and sometimes that means to repeat itself.
6. Updating documentation
Effective documentation must be constantly updated. This is surprisingly challenging. We can start our project with the best intentions and great recording, but as our software evolves and we get going quickly, it can be easy to fall out of rhythm. How can we get that? Dedicating time to it. When finishing the sprint, we need to document what’s worked.
7. Writing documentation easy to contribute to
Being easy to contribute means it’s also easy to keep updated. The simplest ways to make documenting easy to provide are using software such as Notion: This app allows users to have blocks of documentation, on-live editing with other team members and access to changes history.
8. Writing documentation easy to find
It is as useful as easy to find. Keep documents updated and link with more spread documentation when necessary helps to maintain the ease to find, detail, and improve all documenting.
9. Four eyes observe more than two
As much as possible (unless there is a person on the team dedicated only to document) it is better for documents to go through a review from some work colleagues. Let’s remember you don’t make the recordings for yourself, but the rest of the team. A double-check makes ambiguity avoidable.
Good practices
Documenting can be awkward and have a high initial cost, but in the end, the best way or example when planning documenting is…
If a new person who can help me in my post joins (for example, a Front-end Developer), what would be more expensive?: Teaching all procedures of work, structure, and planning, or giving detailed documentation and only having to solve doubts.
On the other hand, there’s the cost of opportunity and productivity of new incorporations, without documentation and detailing of all work processes. The person starts being productive after 30 to 45 days; with documentation, it could be 10 to 15 days.
This is why we must keep in mind, aside from the rules of documents, a series of good practices (more commonly called… common sense), 3 pretty basic principles:
- Don’t produce documentation for yourself; make one you’d like to read. Plan it as the typical GitHub repository to install a library… all documented and well-specified, with all steps and details. What’s that good for? Well, that’s good for everybody who makes what you’d like to receive. And obviously… you are free to comment and ask more details on any recordings that seem incomplete or lacking detail.
- Orthography. It’s clear there can be small errors of orthography, but let’s plan the documentation with a basic level of professionalism, (we are not in high school), things as basic as accents, a new paragraph starting with an uppercase letter, etc.
- Format. Applying style and graphic touches to documenting, adding images, headlines, colors or blocks to attract the attention, those are your friends. When you write, you’ll see many types of blocks.
With all the above mentioned, let’s take a look into a brief example:
An example of documenting
🚫 What not to do
To install a library, we simply drag it to the project, we set it up, and it should run normally. From there, you’ll only need to consider calling it through callAction on the coding line; and our service will execute.
Be careful, because if the environment is not configured correctly, it is possible for it not to work. Speak with Fran about it if you have any issues.
✅ What to do
To proceed to have an active service, we’ll need to download the respective library.
Once the .zip is downloaded, we must incorporate it to our library, you can see information on how to add new libraries, you can see more info about how to add new libraries in “add new libraries to the project” (link to another page)
We must configure the service in our environment, it’s important to have in mind STAGING and PRODUCTION services, it is possible for the service not to function correctly when being on STAGING for the loading speed.
The default configuration is the following.
Once we have installed it, we simply must call the function to launch the service, to call the function, we proceed to:
In case we’d like to erase one of the points, we’d execute it going through the ID of the point (in this case, annotation) and with the corresponding function.
As you can see, it takes a bit more work, but we are providing this complete know-how of a process to the company, which you may not see again, but new people joining will appreciate it a lot.
“Documenting is an investment. An investment in scalability, good practices, and partnership”.
Did you like the post?
Clap! You can clap up to 50 times, and many more people will find and know this post, and of course… don’t forget to share.
Let’s see that applause!
Special thanks to my colleagues and friends, Pedro Cordero, David Stanete, Ruben Dario, my entire Creditas squad and all those who have helped me complete this article. Thanks!
Interested in working with us? We’re always looking for people passionate about technology to join our crew! You can check out our openings here.
Other articles that may interest you…
