What should be documented in a technology project

What the company needs to be able to recover when the team or supplier changes

In a technology project, the decisions, the responsibilities, the connections between systems, the essential configurations and the operating procedures should be documented. With this information, the company can understand and change what was built, even when the team or supplier changes.

Without that record, any change, whether planned or unexpected, such as an employee leaving, a contract ending or a team being reorganised, means losing essential knowledge and becomes a problem of operational continuity. The company only discovers what is missing at the moment it needs the information, usually in the face of a failure or an urgent change.

What information is worth the effort of recording

The starting point is decisions and the reasons behind them. Knowing that an integration sends data in one direction only is useful, but knowing why, for example to avoid changes in two places, stops someone from modifying it later without understanding what is at stake. To this are added responsibilities and reference contacts: who validated the decision, who answers for each system, each type of data and each approval, and who to turn to if it needs to be changed. The distribution of responsibilities between platforms was developed in the article on how to define the role of each system in the company's operation.

For integrations, it is worth recording which data moves, in which direction and how often, so that the company knows what depends on what, a topic we covered in the article on how to choose how to integrate enterprise systems. As for configuration, environments and access, the company should know where the systems are hosted, which accounts exist, who manages them and what the authorised procedure is for recovering access. This stops the company losing control of a system when the person who managed it moves on. Documenting access does not mean recording passwords or gathering them in a document: credentials should remain protected by appropriate mechanisms, controlled by the company.

Finally, procedures for operation, maintenance and recovery: how to restart a process that has failed, how to correct a record, who to contact and what to do when the connection between two systems stops working. With custom software, it is useful to separate two things. It is important to define from the start which technical documentation will be needed to operate, maintain and evolve the solution, and the terms on which it will be made available to the client. The right to access, use or modify the source code, however, depends on the contractual terms agreed with the supplier, and is not guaranteed simply because the software was developed to order.

An example: the integration only one person knew

Imagine a company where the integration between the CRM and the invoicing system was set up by an external supplier two years ago and has since been looked after by a single employee. When that employee leaves, simple questions arise with no answer: why the address is only updated in one direction, what happens when the synchronisation fails overnight, who is responsible for managing the hosting service account. The company has to reconstruct the answers from the behaviour of the systems, at the risk of changing something that was set up that way for a reason. With older integrations, or ones that depend on external services nobody has access to, that reconstruction can be complex and take time, testing and technical intervention.

One page of documentation per integration, recording the purpose, the direction of the data, the frequency, the person responsible, what to do in case of failure and where the accounts are, is a starting point that would turn the same departure into a handover and not an investigation. It is not enough in every project: for more complex integrations, it should be complemented by technical documentation.

Who maintains the documentation and when it is updated

There are two distinct roles. Someone in the company should be responsible for ensuring that the documentation exists, is complete for critical systems and is accessible to those who need it. Who updates it day to day depends on the project: it may be the internal team, the supplier or both, and that split should be defined from the start. Whenever a relevant change is made, whoever carries it out should ensure the corresponding documentation is reviewed, in line with the responsibilities established.

Changes to integrations, access profiles or critical procedures are recorded when they happen. A periodic review, for example annual, serves to detect outdated information and does not replace that continuous updating. The same goes for decisions: they are recorded when they are made, because reasons are quickly forgotten and, by the end of a project, only the results remain. A short note with the date, the decision and the reason, written at the time, is worth more than a long document written months later.

Location matters too. If the documentation exists only in the supplier's systems or on one employee's computer, it is lost precisely with the change it was meant to prevent. It should be in a space controlled by the company and accessible to those who need it.

What does not need to be documented

Documenting does not mean reproducing information that is already available, up to date and accessible in a reliable source. The access and change logs generated automatically by the systems, for example, do not need to be transcribed, although it may be necessary to document where they are, how they are consulted and who has access to them. The distinction between these logs and project documentation was explained in the article on digital transformation in regulated sectors.

What matters is documenting decisions, business rules, specific behaviours and exception procedures, that is, whatever cannot be understood just by using the system. The depth should follow criticality: a system on which invoicing depends deserves more detail than a support tool used by one person.

Documenting in order to change

A realistic starting point is to choose the two or three most critical systems or integrations and prepare, for each, a summary that someone else can use. This makes it possible to identify knowledge that still depends on specific people and reduces the impact of future changes. A simple test helps assess the result: ask someone who did not take part in the project to explain how the system works and how to recover from a failure, based only on the documentation. The questions they cannot answer show what still needs to be documented. This is how documentation fulfils its purpose: allowing the company to maintain and change its systems without depending solely on the memory or availability of particular people.