Do It Or Suffer: The Criticality Of Documentation in IT

Posted On 30 Oct, 2023

Introduction: How Important Is Documentation In IT?

Documentation is like a roadmap which you have with you, especially when you are lost in a jungle.

Imagine you’re an engineer working on a systems integration project.

The project is complex, with many different systems that need to be integrated, and you’re struggling to make sense of it all.

Do It Or Suffer: The Criticality Of Documentation in IT

Without any documentation to guide you, you will feel overwhelmed and uncertain about how to start the project.

You will try to make sense of the different systems, but you will more often than not, get lost in the details and be unable to see the big picture.

Without any reference materials, you will not be sure what’s supposed to connect to what. You will fret and fume about making costly mistakes.

Now, imagine that you have a detailed map of the jungle, and a guidebook with information about the different plants, animals and landmarks you’re likely to encounter as part of your journey.

The Benefits Of Documentation Vs Lack Of It

Do It Or Suffer: The Criticality Of Documentation in IT

The Benefits of Documentation Lack of Documentation
Clear communication and understanding of requirements and objectives Miscommunication and poor coordination among team members
Identification of potential challenges and errors Delays and cost overruns due to fixing mistakes after they happen
Reference for troubleshooting and maintenance Difficulty in troubleshooting and maintenance
Accountabilities among team members Lack of accountability for mistakes and errors
Easier to scale and expand the system Difficulty in scaling and expanding the system
Training and onboarding new team members Difficulty in training new team members

In short, having proper documentation in an IT systems integration project is crucial for the success of the project and helps to avoid a lot of problems that can arise from lack of it, such as delays, cost overruns, and difficulty in troubleshooting, maintaining and scaling the system.

Moreover, it helps to have a clear communication and understanding of requirements, objectives and accountabilities among team members.

Like the guidebook, documentation in an IT project provides a clear direction, helps identify potential challenges, and serves as reference, during the integration process. 

Think of them as navigation systems. They ensure that the project is on track and that the end product works as intended.

Good documentation is essential for successful systems integration projects, just as a map and guidebook are essential for finding your way through a jungle.

The two case studies below will help you understand the importance of documentation, even better.

An International Airport Does Not Take Off As Expected

Do It Or Suffer: The Criticality Of Documentation in IT
One case where lack of documentation led to significant problems was the construction of the Denver International Airport (DIA) in the United States.

The project was plagued by a number of problems, including cost overruns and delays, which have been attributed, in part, to a lack of proper documentation.

The construction of DIA was troubled with miscommunication and poor coordination among the various contractors who worked on the project.

Many of them did not have accurate and up-to-date information about the project’s specifications, design and schedule. This resulted in errors and mistakes that had to be corrected later at additional cost.

One specific example of the problem was the lack of proper documentation of the systems and subsystems that had to be integrated in the baggage handling system.

  • The baggage system design was not well defined. The project was kept on hold for months as this system was redesigned.
  • The new baggage system was not properly tested. It was installed in the airport before it was fully functional, causing further delays and additional costs to fix it.
  • The lack of proper documentation also led to a lack of accountability among the contractors and sub-contractors. It was difficult to determine who was responsible for specific mistakes. This resulted in wasted time and money as the project progressed, with multiple contractors blaming each other for delays and errors.

In total, DIA was opened 16 months behind schedule and $2 billion over its original budget.

These delays and cost overruns have been attributed in part to the lack of proper documentation and poor coordination among the contractors and sub-contractors. 

This scenario highlights the importance of documentation in large-scale engineering projects and shows how a lack of it can lead to significant problems and wasted time and money.

An Advanced Retail Store Software Implementation Turns Into A Nightmare

Do It Or Suffer: The Criticality Of Documentation in IT
Another case where lack of documentation led to significant problems is that of a retail store.

The company decided to replace its outdated retail management system with a new, more advanced system. One that would be able to handle the large volumes of data and transactions generated by the company’s stores.

The integration of the advanced retail software system, however, was beset by problems from the start. 

The company did not document the specifications of the new system. There was no clarity on how the software was supposed to interact with the existing systems.

  • The engineers and technicians working on the project were often confused about what needed to be done.
  • The team in charge of integration was not trained on the new system and there were no proper instructions on how to integrate it.
  • This led to errors and mistakes that had to be corrected later, causing delays and additional costs.
  • What’s more, the team was not able to test the new system before the integration. This led to the system not working as expected and causing interruptions in the company’s operations.
  • The lack of proper documentation also meant that it was difficult to keep track of the progress of the project and to identify which specific issues were causing delays and problems.
  • The whole thing resulted in wasted time and money, as the project progressed. Multiple engineers and technicians blamed one another for the delays and errors.

In the end, the integration of the new software system was completed, but only after significant delays and at a cost that was several times over the original budget. 

This case highlights the importance of documentation in systems integration projects and how a lack of proper documentation can lead to wasted time and money.

The scenario is the same for all projects, of any size – lack of documentation leads to mistakes, poor functionality, delays, cost-overruns and avoidable maintenance issues.

Documentation Is A Life Saver For IT Engineers

Do It Or Suffer: The Criticality Of Documentation in IT

While most engineers hate to document, almost all engineers appreciate a good technical document.

This could be a design document, troubleshooting tips or an integration checklist. It could be a blog someone posted to help you.

The important point is that good documentation saves everyone’s time.

Documentation really becomes salient when something breaks, something needs to be upgraded, or integrated with another system.

Have you ever inherited an IT department with no documentation and you have had to manually trace cables?

As insiders, we all know that this is not fun. We are also acutely aware that our engineers aren’t blessed with unlimited memory.

So, the only way to make sure we have what we need, when we need it, is by documenting it.

We know that our engineers go on vacation, maternity leave or even leave the company.

We don’t want to trouble them when they are having a good time with their family, do we?

Do Tools Help With Documentation? 

Do It Or Suffer: The Criticality Of Documentation in IT
Tools do help with documentation, as they can provide a convenient and efficient way to create, organize, and share documentation.

They can also make it easier to track changes, maintain version control, and collaborate with others.

However, what is important is that the use of tools alone does not ensure effective documentation.

For example, simply using a tool like Confluence or JIRA, or even Google Docs to create documentation is not sufficient.

The team must be disciplined to regularly maintain and update the documentation, and to ensure that it is accurate, complete, and relevant. If the team is not disciplined in their approach, the tool may not be as useful as it could be.

In short, while tools can certainly facilitate and streamline the documentation process, they are not a substitute for discipline and effort.

The proper use of tools and the discipline to maintain accurate, up-to-date, and relevant documentation are both necessary for effective documentation in systems integration projects.

At Consltek, We Love Documentation

Do It Or Suffer: The Criticality Of Documentation in IT
We create all kinds of documentation when we onboard a customer for any of our IT services, and especially for Managed IT Services.

That includes network diagrams, patching processes, inventory of items, Knowledge Base articles, troubleshooting documents and more.

What’s even better, we keep updating and adding new stuff to our document repository, all the time.

As proof of this, in the last 6 years, we have created close to a thousand documents. We actively use the document repository to save tens of thousands of hours for ourselves and our clients.

Our interns and L1 engineers are trained first to create diagrams. Then craft documents as part of their training. We even have a document on “how to edit a document”

When you sign up for our MSP service, you automatically get outstanding documentation whether you like it or not.

 

Article by:

Rajesh Haridas

Rajesh Haridas is the founder and CEO of Consltek. He brings in 20+ years of experience working in the technology industry.

Boost IT Growth In Healthcare

Set up a no-obligation consulting session