Image for post
Image for post
Photo by Kaleidico on Unsplash

Why is IT documentation still left out?

Years have gone by and technologies have evolved but our documentation habits didn't

Danilo Ferreira
Sep 20 · 3 min read

Although everyone knows how much life has been digitized in recent years, not everyone understands how many tasks and projects IT teams have to perform and take off the paper so that technology become present, playing its role as a facilitator.

In all my years working in the IT industry, I’ve noticed a pattern. It is very easy to get into the execution mode and devaluate some best practices that aim to organize and increase the success of our tasks — tasks that drive the role of technology in society. One of these best practices is to document, which is depreciated in the name of delivery.

Why do I say that?

Because understanding how things work in a team is a basic requirement in any company. Regardless of the management model, having organized documents that help new employees to understand which processes and tools are important is something that maximizes the potential of any team.
However, it is not just a matter of onboarding and the learning curve. The IT documentation is created doing business analysis, that is, it answers the question of what needs to be done by the technology team for the company’s results to be achieved.

Furthermore, good documentation helps managers understand how the team can organize and produce at its greatest capacity.

I’ve been thinking about it a lot because everywhere I’ve been, I hadn’t had good experiences with documentation. Unfortunately, I’ve never got to work in a team with good documentation that would serve as a basis and help us to have an overview of the sector and how it affected other areas and projects.
In most places, information is always in the head of someone who already has experience within the team. For example, someone who has been immersed in a team for five long years can understand very well how certain applications communicate. But what happens if that person leaves the company and their knowledge is not documented anywhere?

In my view, failing to document processes not only reinforces dependence on people but means a waste of time and money.

Imagine how many hours an entire team spends trying to find out, for example, how the infrastructure works — since there is already someone with fresh information in their head, who could have designed this explanation easily and intuitively.

Another scenario: imagine putting on paper all the losses caused by the turnover of a team that works without any documentation. The sum can be absurd.

I think of IT documentation as something that everyone knows is important — but that few companies, whether large or small, do with ownership. And that goes for everything: business rules, architecture, quality testing, security policy, IP table, source codes, scripts, backup information, hardware, and more — many others.

Documenting at the end of the day is a competitive advantage, especially in a market as fierce as technology. It allows a more organized, dynamic, proactive, and easy to understand IT environment — that’s why I believe that investing in this action brings countless advantages not only to IT but to the company as a whole. It facilitates the onboard of new employees, reduces the risk in eventual turnovers. But more than that, in the end, if we have a minimally documented business process, a minimally structured architecture design, a drawing of how the application ecosystem relates, which machine, which port, which data at which address, how fast will we fix a bug or deploy a new feature?

So, even if your IT team is focused on executing and delivering results, it is recommended to think of alternatives that enable documentation. Hiring someone specific to design and document can be a choice, as well as separating a moment from the team — inside or outside the sprint — for everyone to collaborate and share knowledge. Again, on this topic, I have more questions than answers.

What is your experience with this topic? Does your team have time to assemble and keep the documentation up to date? Tell me here in the comments.

Blog sobre Danilo Ferreira

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store