Importance of documentation

Documentation is a part of our work as developers, which can guide us in the different phases of development. What is documentation, what diagrams does it include, in which cases is it important to carry it out,

The documentation of the programs is an extremely important aspect, both in the development of the application and in its maintenance. Many people do not spend time on this part of development and do not realize that they lose the ability of a easy maintenance and part of its potential code organization, in a more flexible and scalable way. Even the documentation can help us to reuse parts of the application and especially the design schemes.

Of course, by examining the code we can understand it, but it would take time proportional to the size of the application. Even if you are the one who later has to support the application, even if you know the code inside out today, it probably won’t be in a few months or years.

This article addresses a topic that is important, such as documentation, but that applies more to project development than to programming itself. If you’re reading this to clarify concepts to help you just throw away your first few lines of code, maybe you could skip it. In any case, it is very interesting to know things that you will have to worry about when you are making more complete and complex applications than the simple code of basic examples on a language that you are learning.

What is documentation

Documentation, as its name suggests, is all kinds of information that helps direct the efforts of the development team and also help to understand the application architecture and design over time. For the client, it can be all the information that guides them when using the application once it has been delivered.

The documentation of a program begins at the same time as its construction. In fact, the most normal thing is to start by doing schematics of program parts, functionality, interfaces, etc. so that, by the time we start programming, we are very clear what is going to be developed and how are we going to do it.

The preparation of the documentation does not end with the delivery of the application, since during maintenance it is necessary update it to reflect the changes that have had to be done to create new functionalities.

Don’t confuse documentation with code comments

It is important not to confuse documentation with code comments. In reality, a code should be so simple and clear that it does not require comments. If you have to comment a piece of code because it’s too complex to understand by reading, you’re doing something wrong.

Therefore, they must avoid code comments at all costs and, instead, we have to find programs that by reading them we can perfectly understand what they do.

When is the documentation done?

Many people think that the documentation of a program, at least the one that indicates how it is going to be developed, has to be done all at the beginning. Then eventually present some parts to the client for validation and finally schedule what was agreed.

This is not like this. The documentation accompanies the different stages of the project, which are iterative and constantly improve. There are some parts of the documentation that are done at the beginning, such as the domain modelwhich helps us clarify what the client’s vocabulary is and fixes the minimal set of words that we will all have to use when creating the pieces of software. It also helps relate the different entities that the program must manage. Other diagrams that can help a lot to understand the problem and the flow of actions of the application are the use case diagrams and the state diagrams.

Especially at the beginning of the development of an application, where it is advisable to dedicate efforts to the most complex parts or those that represent the greatest challenges for the team, it is important to carry out class diagrams of what we are going to develop. In fact, by making these diagrams, in part, we are already programming, although not with code. Then, throughout the different phases of development, new modules will be created that may require new diagrams. However, as the project progresses, it will not always be necessary to carry out documentation, since we will surely be working on simpler modules or the modules respond to an architecture similar to that of others already existing in the application.

What diagrams are included in the documentation

It is a little early to be able to define what types of diagrams you will need, since we are in a programming initiation manual, but generally they will be class diagrams and some state diagrams. You may eventually need some object diagram and some activity or sequence diagram. For requirements gathering we will have use case diagrams and interface mockups. Generally all these diagrams are made with UML, since it is a language widely adopted in the industrythat everyone understands.

If you want to delve deeper into this part, it is interesting to see a UML course or, better, sign up for EscuelaIT, where we learn UML on the go throughout the different development disciplines.

Documentation Yes or no?

On the need or not to do documentation we can enter into an infinite discussion. There are development teams that don’t do it and maintain that “code is the best documentation“. The opinion of these professionals is totally valid, given that good code is self-explanatorybut you have to be very good at designing and programming with extreme quality standards for it to be like that.

So, if we were to decide between bad code with great documentation or quality code with no documentation at all, it’s a hell of a lot. better quality code, because it will be perfectly understandable. However, not all of us are at that level, so a little help from the documentation can’t hurt. At the same time, you have to put all the necessary efforts to be able to develop like the angels to achieve success and excellence in software development.

Against the documentation it is also pointed out that it often becomes out of date due to design changes made in maintenance or during development. Although it is true, this is compensated with the care of keep it updatedyes it is true that it is a job that is added to the project.

In favor of the documentation it can be pointed out that it is much easier participate in design meetings if we have diagrams in front of us that visually indicate the class proposals on which we intend to work. If a person joins the work team, it will also be very easier to start actively contributing to the project if you have some diagrams that make it easier for you to understand how this application has been developed.

Unfortunately, you have to study a lot more to be able to understand what documentation is and have the experience to know when to do it and when not to do it, as well as what diagrams should be done.

Documentation traditionally understood in secondary education courses

Next I am going to leave some notes on what the documentation is like, as it is explained in the secondary education in Spain. Perhaps it will serve to clarify some additional points.

Updated: The article block that follows is the original one that was published in 2006. However, reading it again after a few years (we are in 2022) and based on my professional experience, I must say that the text is quite academic , maybe too much. Most of the time this type of documentation is not done, at least not all of it, but it is what was explained to us in class at that time. I prefer to focus on the documentation that is useful for the work team, during the development stage and during maintenance.

Again, you may not understand everything, and you don’t really need to if you’re learning to code now. If you want to deepen and acquire knowledge that will serve you professionally to program like a ninja, you need time and access to quality and rigorous training, which allows you to fully understand what documentation is, what it includes, and when to do it. For this, the master’s degree that I mentioned from EscuelaIT is an excellent opportunity to learn delicate issues like these.

That being said, I’ll leave you with the notes that were published at the time about documentation.

Types of documentation

Documentation is clearly divided into two categories, internal and external:

Internal: It is the one that is created in the same code, either in the form of comments or information files within the application. External: It is one that is written in notebooks or books, totally unrelated to the application itself. Within this category is also electronic help. What documents are included in the documentation

The technical guide

The technical guide or technical manual reflects the design of the project, the coding of the application and the tests carried out for its correct operation. Generally this document is designed for people with computer skills, generally programmers.

The main objective is to facilitate the development, correction and future maintenance of the application in a fast and easy way.

This guide is made up of three clearly differentiated sections:

• Load notebook: It is where the solution or design of the application is reflected. This part of the guide is intended for programmers only. It must be carried out in such a way that it allows the division of labor
• Source program: It is where the coding carried out by the programmers is included. This document may, in turn, have other documentation for its better understanding and can be of great help for the maintenance or improved development of the application. This document must have great clarity in its writing for easy understanding.
• Tests: it is the document that specifies the type of tests carried out throughout the entire project and the results obtained.

But in any case, the documentation that is delivered to the client will have to coincide with the final version of the programs that make up the application.

Once the program is finished, the documents that must be delivered are a technical guide, a user and installation guide.

The user guide

It is what we commonly call the user manual. It contains the information necessary for users to use the application correctly.

This document is made from the technical guide but the technicalities are suppressed and it is presented in a way that is understandable for the user who is not an expert in computing.

One point to take into account in its creation is that it should not refer to any section of the technical guide and in the event that some technicality is used it must be accompanied by a glossary at the end of it for easy understanding.

the installation guide

It is the guide that contains the…