The importance of documenting things — and tips to a good documentation
Good documentation can be the key to success for a team. There are several things that can be documented: processes, decisions, ideas, task delivery control, scope cuts, and so on. Everything will depend on the needs of each team. This need has been presented more frequently in recent times due to the moment we are living. The vast majority of companies have migrated to remote work, and with this many changes have been implemented. If it was already important to maintain adequate documentation before, for reasons such as organization and traceability of information, imagine now that communication between people is suffering the impact of social distance.
There are several advantages to producing good documentation. The first of these, as mentioned earlier, is the organization. Regardless of the purpose of the document, it is essential for a team that all members have access to what they need to do their job well, quickly and efficiently. And things can only be quickly found if we know where to look, so organizing is vital.
Another great advantage is maintaining the traceability of information. This is very important because it will probably be necessary to revisit some decisions made. It is important to note that, if there is no record of such decisions anywhere, the team has to look for the information in more informal communication channels, such as chats. And because they are vehicles of daily communication, chats end up having immense histories, making locating specific subjects very difficult. This directly impacts the time spent by each person to access the information. This time could be saved and spent on tasks that make the most sense for the team. Consequently, saving time also results in faster deliveries, which tends to help the team meet deadlines more easily.
Still talking about time, it is also worth remembering that in the absence of a good document where to look for information, people will often ask third parties, spending the time of other colleagues, sometimes from other teams, to seek information that could have been sought once and documented later. The problem can grow exponentially if the team’s communication is bad, so there may be more than one person going after the same information, as it is not shared with the rest of the team when discovered. Add to this the possibility of being a company with people working remotely from different parts of the world, with different time zones. In this case, the answer to an important question can take a long time to arrive.
It is important to remember here that each team must decide what and how to document the information based on their own needs, and the number of team members who are willing to write and contribute, as not everyone is very fond of this more organizational part. This is exactly why it is essential to emphasize that the document does not have to be an article, full of rules and good practices. The goal is not to lose a lot of work time, but the opposite: document everything vital to save time in the future.
This is where you can ask yourself: how to make documentation simple and efficient? Below are some tips on how to produce a document that is easy to understand and modify, and at the same time quick to find what is needed:
- Instructions at the beginning: Provide team members with all information related to the document, such as the main purpose, who can edit, how to make comments, how to inform the team about updates, how the document is organized and how to create new sections;
- Easy access: If one of the main objectives is to streamline the team’s work, providing vital information quickly, it is essential that it is available in an easily accessible place. A good example is Google Docs. The link to access the document can be displayed in a place common to all team members;
- Give complete information: If you need to exemplify something, or provide any information or instruction that is not directly in the document, provide the access link for this data directly in the document. Ideally, no team member has to search the Internet for information that is incomplete in the document;
- Organize well: Use familiar terms to divide the document’s sections and provide a summary at the beginning. Ideally, the title of each section can serve as a direct link, so that the user does not have to look for what page the content is on;
- Allow comments: allow the team to comment on the content by adding questions or observations. Once again, Google Docs presents itself as a perfect tool for the occasion. In addition to allowing you to select a part of the text to comment on, you can reply to the comment box, and notify members directly in their e-mails. It is also ideal that the comments are not deleted, as history can be very important in the future;
- Notify updates: Keep the team always up to date with changes to the document, or adding content. The information you are entering now may be needed by someone right away! If possible, when informing the team of an update, provide a direct link to the point in the document that has been modified, or it may be very difficult for your colleagues to find where the change is. In Google Docs, you can insert bookmarks anywhere in the text and copy the link to send to team members;
- Find the balance: When writing new information, be brief enough not to be tiring and waste a lot of time, yet descriptive enough to leave no room for doubts and second interpretations. A great tip for finding this balance is to write as you speak. Using a more natural and friendly language can be more explanatory than a pompous explanation full of technical terms. We are not looking for a thesis, just a document that facilitates the day-to-day work;
- Always use accessible language: As we are talking about documentation in general, without focusing on any topic, you may need to use sensitive words at some point. When in doubt, always be informed! It is essential that no one feels invaded, embarrassed or negatively affected by any term. At the end of this article you have a direct link to the Microsoft documentation tips page, which has a very interesting collection of inclusive terms;
- Add a touch of fun: It is important to keep the team excited, so you can add more colloquial terms or even allow the use of emojis. Everything will depend, of course, on the objective and level of formality of the document, as well as on the relationship between the team members. Oh, and don’t forget to let the team know about these points too (at the beginning of the document, in the instructions section).
You can find other tips in the links referenced at the end of this post. To illustrate the tips above a little better, here is a screenshot of the initial part of the document “Cross-Platform” of our team, which currently develops native mobile applications. This document aims to keep track of the things that are common to both teams (Android and iOS), and that often need third parties to respond:
Based on the screenshot above, we can see that the document already starts following some of the tips previously mentioned: clear and brief instructions, located at the top, presenting the necessary links. The document is divided into sections according to themes, with the sections all organized on the side of the document (as shown by the arrow in the description). And finally, some emojis (which continue to be used throughout the length of the document), encouraging the team to use them as well, and making the task of documenting and organizing the information flow a little more fun. In addition, the document is available on Google Docs, with the direct link fixed in the group chat, also contemplating the easy access tip.
The results that the team experienced (and continues to experience daily) speak for themselves and prove the benefits exposed above. The team members contribute with essential information and seek to find what they need there before asking third parties, greatly reducing codependency among members. It is important to note that this is a remote team, and people are not always online and available at the same time. The document became a source of essential information for the correct execution of tasks. A little time is spent now, a lot is saved in the future!
References:
