Software documentation: an advantageous condition

One of the cornerstones of digital solution design at Antreem is the connection between analysis, design and development activities.
We follow the product/service from its conception to its release into production, through all its growth phases. However, this modus operandi is only possible by following a tricky operation that is often downplayed: preparing the documentation. Although often overlooked, this process is actually fundamental to any project involving more than a few lines of code.

Precise documentation is a potential two-fold advantage, both for the person commissioning the project and for the team working on its implementation. In the first case, it will help the client to have a clear, defined and written idea of what the objectives of the service are and to keep track of the work done until the application is delivered. The documentation also reduces the time it takes to implement new functions, giving all suppliers a clear and immediate overview of how the application works. 

In the second case, the documentation also helps the solution developer to avoid running into blocks of code that are difficult to understand, especially when the team consists of several people. Another common case are situations in which one returns to work on a project months or years after abandoning it: everything that was very clear then will be less clear today. Finally, when working on a new project (perhaps to carry out maintenance) it is always very important that those who have worked before us have left a good deal of documentation.

One of the most common mistakes made in this respect is when working closely with all the actors involved in the project: in these situations it is more convenient to ask directly (perhaps verbally) about parts of the project that we are approaching for the first time. This approach, while certainly time-saving in the beginning, has a number of shortcomings in the long term: some of these were particularly amplified by the increase in remote work caused by the pandemic period; if a particular project had not been adequately documented, dozens of calls (often in groups) were needed to get a clear picture of the work done, as the person who used to be our desk neighbour was now 100km away. We were unprepared to deal with the amount of alignments needed, thus wasting a lot of time that could have been saved with some prior documentation.

Several types of development documentation can be compiled in relation to a project, including the following:

• analysis and functional documents, such as the AFU, are prepared and compiled before the start of any development activity and outline the behaviour of a software, as well as taking into account the customer’s requirements. This type of document is always drafted by developers and designers working together to achieve a truly implementable result;
• technical documents: there are various types, from the more general ones such as the Technical Analysis (ATE) which indicate what type of technology will be used for the project and why, to those which are compiled as the project progresses with useful information relating to the technologies used;
• the API documentation: these are fairly schematic documents that define how the Front-end and Back-end communicate. These should also, as far as possible, be ready before the start of development in order to avoid certain problems in the race;
• comments in the code: these are the most basic form of documentation that is obviously produced during development. It is important that the code is well commented so that you do not have to constantly bounce between different documentation files.

These are mostly documents concerning the Deliver phase of our flow. Other types of ad hoc documentation exist for the Discover and Design phases.

Ideally, each of these documents should be filled in and, on each occasion, it should be decided who will review them. For each phase of our workflow, having accurate and up-to-date documents allows us to proceed effectively with the work and optimally interconnect the analysis, design and development phases. It is therefore important to rely on a technology partner who attaches the right importance to the drafting of comprehensive documentation: an essential and valued element in the realisation of a quality project, even in the long term.