The application prepared wisely

What is a technical documentation

Probably non-technical people wonder what this technical documentation is and why they should pay attention to it. I think that it is easiest to compare it to other documentation prepared, for example, during the construction of a building or other infrastructure. In the case of building a house without such technical documentation, it is impossible to start work for legal reasons. Have any of you wondered why officials require this? Of course, there are many reasons for this, but I will use one factor - safety. If a potential project was to endanger human life or health, then of course such a project will not be approved.

Ok, we talk a lot about the technical design of buildings, but what is the technical documentation of the application about? Well, it is similar. Such documentation should contain the most important assumptions about the application such as:

• environments and on which systems the application is to run,
• what potentially traffic is to be handled,
• and of course the most important, the description of the functionality.

If we use the analogy of safety in construction projects, such technical documentation of the application gives a sense of safety to both parties, the ordering party and the contractor, each party knows what to expect. So the rule of win - win.

As we already know what it is, let's move on to another bothering issue - why do we need technical documentation? What can motivate us to create it? People are usually lazy, and that's good, because we would live in the jungle and hunt mammoths so far, and thanks to the fact that we are lazy, we have what we have, i.e. technologies, medicine and other luxuries that fill our lives like xbox or tik tok :)

If people are lazy, you have to find some other way to create very good quality products. Any written arrangements are the solution to this. If a project lasts more than a few weeks, it's hard to remember all the details that were agreed at the beginning. If we did not write it down, either we would waste a lot of time re-establishing something or redetermining something could negatively affect the already existing elements of the application. When we create documentation, we know from the very beginning how a given application is supposed to work and at this stage we are able to detect inconsistencies or conflicts in individual system modules, and the earlier we find them, the more we will save.

Who should prepare the documentation?

Personally, after many years of experience, I believe that the documentation should be prepared by both parties of the contract. The contracting authorities know best what they want, and the economic operator should support the contracting authorities with its technical knowledge.

I encourage everyone who professionally deals with designing and creating applications to create their template for technical documentation. For their part, in the further part of the article, I will indicate what should be included in such documentation.

Why do I encourage you to create such a template? Because it will help both sides frame their needs. More than once I have come across the fact that clients came to me with 30-page documents describing in a very laconic way how the application should work, despite the fact that there was so much content there. Entering this in the appropriate template will help both sides to control unnecessary word formation that does not affect the description of the functionality in any way.

Of course, the contracting authority may not always have the appropriate knowledge, and sometimes to describe everything accurately, so the division of these responsibilities should be established at the very beginning and I think that you should be very flexible at this first stage. It is a good idea to organize sessions to discuss the various stages of creating this documentation.

Do I need a graphic design when creating technical documentation?

I think a short introduction to what is a graphic design of a web application will be useful here. As you can guess, it is an image or set of images (graphics) showing what the application will look like. If someone has already encountered the graphic design of a website, he/she can of course easily imagine what to expect. It should be noted, however, that when it comes to graphic design of the web application, we do not focus so much on the beautiful graphics in itself, but on the usability of the application.

When it comes to usability, one of the motives that pushes us to create a graphic design is to find out if our application will be convenient for users before we start building it. In this way, we will save a lot of time, if at the end of work on the application we suddenly find that some of its elements are not functional from the point of view of the future user.

Since we already know what to consider when deciding whether to commission a graphic design, we still have to answer the question: Who should prepare it? The answer immediately comes to mind - Graphic Designer. However, this is not entirely correct as there are different designers. The application design should mainly present the data flow and how future users will use our application, so it is the best to prepare the project by UX Designer, a person specializing in user interface design. UX Designer should work closely with the owner who knows best how the application should work.

It may not seem obvious at first glance, but working on a graphic design is much cheaper than the work of developers who would have to unnecessarily change functionalities after their implementation.

How to prepare technical documentation

To answer this question in detail, a separate article would be needed. In this part, I will focus more on the general information in order to better understand what such documentation is. At the beginning, I would like to point out that there is no model or scientific study for this document. In my example, which I will try to describe here, I rely on my experience in creating such documentation.

To make it easier to navigate through the documentation, it is worth structuring it (divided into chapters). An example structure may include:

1. Project’s title
2. Project’s description
3. Defining the requirements

• language
• technical
• traffic
• graphic
• SEM & SEO

4. IT infrastructure
5. Functional description of the project

• description of the individual modules of the project
• requirements for forms and their validation
• possible functions that the user can perform in the given module

However, before we start describing our application, I recommend that you prepare mock-ups (you can make them by hand, with a pencil or with the help of specialized programs) that will graphically present how our application is to work. This action, as well as the preparation of a graphic design by UX Designer, will help us notice some gaps in the application logic, and will also serve as a great basis for creating a professional graphic design.

Of course, this point about creating mockups can be omitted when the application is very small or when we have such a vision, but from my experience I recommend spending a few additional hours to do it.

Finally, I would like to present other forms of preparing technical documentation. We can distinguish:

• descriptive documentation - textual presentation of the application functioning (it can be in the structure I proposed.
  The advantage of such documentation is that it can be used to describe individual tasks for programmers.
• descriptive and graphic documentation - it is a combination of text and graphic documentation. This is the form of documenting the application that I recommend,
• graphic documentation - presenting the operation of the application in the form of graphics presenting individual states of the application,
• block documentation - one of the cheapest and fastest to prepare, but from my point of view it brings the least tangible benefits, but very good, as a basis for the preparation of more extensive documentation.

Why is it worth creating documentation

We kind of answered this question between the lines. Here, however, we will try to summarize what we have said so far about the technical documentation, with an emphasis on why it is worth it.

In order to quickly answer this issue, it is worth considering whether our application will be large and complicated. If the answer is yes, then we should definitely make these efforts and this investment will certainly pay off in the form of fewer fixes and changes in functionality. If our project seems short, e.g. 1-3 months of work, you can use less complicated documentation, e.g. graphic or block.

It is known that the creation of such documentation will involve some time expenditure, and thus also a financial outlay. However, believe me, from my experience, these outlays are a drop in the ocean if we compare it with the subsequent expenses that have to be incurred when something has not been fully thought through.

Life cases when projects did not have documentation.

At the end of this article, I would like to warn you against the lack of technical documentation and functionalities written on the basis of my experiences and the experiences of my clients. It is known that the preparation of documentation and designs, graphic models takes a lot of time, in addition, the development of the entire concept of a complex application may also take a lot of time. I was a witness when such a process took a year. A lot? It depends, of course, in the project in which I participated, I would say that it could be done in 6 months, but I do not think that a year with very advanced projects is a lot.

Now let's move on to the failures I have faced in my career. The first of them was our private marketing project, the technical documentation of which was written on the knee and when it was implemented and something started to emerge, it turned out that: 

• first, it doesn't look nice (no graphic design),
• second, logical deficiencies in basic functions began to emerge.

Our application seemed quite simple and small, but we finally stopped working and are currently working on the technical documentation and graphic design for it. As a result, the software gained additional functionalities and was thought out in terms of business as a SaaS solution.

Another application in which we had the pleasure to participate was a parabank system that had certain frameworks described and even graphic designs prepared, but in the middle of work on the application, we stopped analyzing further functionalities and preparing appropriate projects, and therefore our work was very slow and we had to do a lot at the end, redo things.

I learned the next lesson from the application supporting HR processes. It is a very advanced application which, due to the complete lack of technical documentation, has been changed so many times that it is impossible to remember it. In the end, the application saw the light of day, but in my humble opinion it could be written in a budget 4 or 5 times smaller.

I think that nothing speaks louder to entrepreneurs than money. So please think about this topic and do not always choose the fastest and cheapest way in the tender, because it may lead you into serious financial problems. I hope that after reading this article you are armed with knowledge that you will be able to use when signing contracts and agreements to make software for your companies.