Managing organizational information and knowledge is one of the top challenges in a company. This issue tends to grow as the organization expands with more professionals and responsibilities.
Making documentation is one of the most efficient ways to deal with this challenge. It ensures organizational and information architecture scalability.
There is a huge debate on the costs of documentation. However, little is said about how expensive it is to own software or architecture without good documentation.
Key points about documentation:
- As with any architectural decision, it is always important to consider its pros and cons. Lack of information results in countless meetings and knowledge gaps when a team member leaves. However, the excess of information can also become an enemy when a lot of work is involved in creating the documentation.
- There is documentation at both the tactical level (which provides a greater view of the code) and the strategic level (which covers both the application architecture and its technologies).
- We can consider documentation a product in which engineering or development professionals represent their users. The goal of this product is to make the team more scalable. One way to measure its effectiveness is to detect how many meetings were avoided once the documentation was created.
- Good documentation must always be visible and available to users, ensuring good knowledge management, scaling faster teams, and avoiding organizational silos. Therefore, a good practice would be replicating all the code practices in the documentation, like Doc-as-a-Code. By doing so, Git becomes the only source of truth, with scalable and updated content derived from the DocOps culture.
