IT project visualization. Types, examples, and tips

Visualization is one of the most popular methods of analyzing and communicating information. This article will try to present several visualization methods in an IT project. It will tell you how to simplify sharing knowledge in a team. 

Is the documentation in an IT project necessary? 

Developers’ opinions regarding the need for creating the documentation are strongly divided. On the one hand, the documentation responds to the problem of storing knowledge in a narrow group of people, an example of which is the Bus Factor and the occurrence of the so-called Heroes in the IT project. On the other hand, documentation, like code, needs to be maintained, so it takes time and money. 

So what should good, cost-effective documentation be? 

• Up-to-date – let’s make it easy to maintain the structure by automating the generation of documentation, e.g., based on code. 
• Available – let all project participants know about the existence and location of documentation. 
• Helpful – let’s collect frequently asked questions and make sure that it is readable by everyone. Let us also consider whether it is needed and its format will be the best. 
• Compatible with UX – we have to predict what information a person who opens such documentation may look for. Data should be easy to find – that is the purpose of documentation. Of course, sometimes text will be better, sometimes visualization. However, it is worth remembering that one diagram can be more effective than a wall of text that is difficult to walk through and which is even harder to hold. With well-structured data, we should easily find or recall specific information. 
• It should have interactive or editable diagrams – if the diagram is created in a different tool and is pasted into the documentation in the form of a non-editable graphic, sooner or later, it will lose its value and become obsolete. 

Types of visualization in an IT project 

Visualization in the IT project documentation can take various forms, and we can divide it into: 

• documentation of tasks and work progress, 
• business (functional) documentation, 
• documentation of the application’s appearance, 
• technical documentation. 

Documentation of tasks and work progress 

It is the most popular form of IT project documentation. It is the basis for assessing the project status, work progress, and project risk by non-technical persons. It is created and used by the entire team and is an essential point for the Project Manager. 

The methods of visualizing this type of documentation include: 

• taskboard – shows currently planned, performed, and completed tasks, 
• burndown – shows the current progress and pace of execution of scheduled tasks. 
• Gantt diagram – presents the scope of work in the form of periods in which tasks in the project have been or will be performed, creating the so-called design lifeline. It also allows you to mark the so-called milestones, i.e., points summarizing a specific set of tasks. 

For an application that other users are using, reports on errors in the application are also helpful. A valuable risk assessment method is to show a specific indicator calculated based on the number and severity of the error priority. Too high a hand value means that the first thing to do is fix the errors. 

Business (functional) documentation 

Business documentation is most often developed when the analyst responsible for it works on the project, but it is not the primary determinant. If there is a need to centralize information, the developer can also develop the documentation responsible for a given functionality. 

There are many methods of visualizing business documentation: 

• bullet points, 
• tables, 
• diagrams, e.g., UML, BPMN, 
• other solutions that easily illustrate the problem, 
• workshop methods, e.g., Event Storming, User Story Mapping 
• event storming 

The Event Storming methodology allows, to some extent, to replace conventional business documentation. It is handy in DDD (Domain Driven Design) modeling because it is based on events occurring in the system. During Event Storming, you go through all the stages leading to a given functionality, which allows you to get to know the system in-depth, and it will also work great as a form of implementation. 

Documentation of the appearance of the application 

Documenting the application’s appearance is extremely important in cooperation with the client. Thanks to it, we can quickly outline and visualize the target appearance of the product and minimize the risk of misunderstood requirements. This, in turn, translates into – especially important from the business perspective – reduction of the costs of introducing possible amendments to the design. 

One of the techniques of comprehensive cooperation is the Design Workshop (Client Workshop). It is a meeting with the client in the form of a workshop. The team dealing with user experience (user behavior) or design, in general, collects requirements for application users (person) and their tasks in the process that the manufactured application is to support. The meeting is also attended by an analyst who links the client, the design team, and a developer who helps determine the difficulty of implementing the proposed solutions. 

Wireframes 

After the meeting, the first wireframes are created, i.e., concepts depicting the arrangement of components and the principle of operation of the application. They are sometimes referred to as low-fi(delity) mockups. Their main goal is to clash the developed concepts with the client. After obtaining the client’s consent for further operation, the wireframes are transformed into high-fi(delity) mockups, i.e., visualizing the application’s appearance, which will be very similar to the tangible form. 

When working with mockups, the style guide is often selected, i.e., a set of colors, fonts, and the appearance of basic components, based on which developers and designers will be able to create a component library and use them repeatedly. This allows you to save time while maintaining the consistency of the application and the use of developed solutions in the future, for example, in a different project for a given client. 

Technical Documentation 

The technical documentation aims to facilitate the work of developers by presenting the current architecture and its arrangements. The central place of its storage should be the place most frequently visited by programmers – the repository or pages generated based on the sources located there. 

In the case of technical documentation, the visualization is usually achieved with the help of unique code processed by appropriate tools. Examples of such tools are: 

• portals or plugins using markdown files (e.g., Github), 
• static website generators (e.g., Docusaurus, Gatsby, Nextjs), 
• documentation generators (JSDoc, doxygen), 
• Storybook, 
• Swagger, 
• Structurizr. 

The primary technical documentation is Readme.md files, which are often supported by Github, Bitbucket, or Azure DevOps. Content is added using the markdown syntax, which allows you to maintain a consistent documentation style for the entire system. It also happens that websites add additional plugins, thanks to which it is possible to add diagrams, the so-called Diagram as Code. The advantage of this approach is that the content is easier to maintain (modify). 

If the Readme documentation is insufficient, you can extend the so-called markdowns through tools that generate static websites. An excellent example of such a tool is Docusaurus. A similar effect can also be obtained using tools such as Gatsby or Next.js, but Docusaurus provides additional functionalities needed for project documentation, including the configured ability to visualize markdown files and ready styles for showing the code on our website. It is also possible to run a design blog to write ADL (Architecture Decision Log). 

The markdown syntax makes it easier to maintain the documentation by styling it appropriately with Readme files. Using such page generators allows us to decide how a paragraph or placed code should look. 

The significant advantage of Docusaurus and markdown syntax are plugins that allow you to add diagrams. An example would be a mermaid. This tool will enable you to generate diagrams using a unique code. This is a much easier way to maintain because we can edit them at any time. The downside of this solution is that you need to know how to generate diagrams. 

However, there is nothing to prevent Docusaurus from using other documentation generation tools, such as jsdoc or doxygen, which allow you to document functions directly from your code – using comments. Thanks to this, the documentation can now be made in the file with the code. 

If we are on the subject of components and automatically generated documentation, it is worth mentioning live documentation. They allow frontend components to change their properties and preview the changes simultaneously. A good example is the Storybook, which supports many libraries (including the most popular: React, Vue, Angular, or WebComponenty). It also has many plugins, and in addition to the component preview and the possibility of its changes, it gives the option of displaying the complete documentation written in markdown. 

For backend programmers, Swagger is excellent. It allows you to generate API documentation and provide more information about the required types. Additionally, it is also possible to test actions created by us. 

For architects, a helpful tool will be Structurizr, which allows presenting architecture using the C4 model. This model allows for the presentation of architecture using four layers: Context, Containers, Components, and Code (the latter, due to frequent changes, is sometimes omitted). 

Summary 

We have presented several tools that will help improve the visualization of an IT project and thus improve the process of analysis and information transfer in the team. Regardless of the examples cited, it is worth remembering always to be guided primarily by the factors of good documentation and the purpose for which it was created. Lack of sense and disorder of knowledge may result in a reluctance to make documentation in the future, which in turn may lead to its obsolescence. 

About the authors:

Leszek Stasiak 

Leszek Stasiak. Senior Software Developer at Synergy Codes. A believer in simplicity above glamour, even functionality. He likes to deal with data processing tasks. In his free time, he is interested in the basics of psychology, striving to be understood adequately by others – as the key to success. 

Pawel Waligóra 

Paweł Waligóra. Software Developer at Synergy Codes. Technologies in which he usually works are mainly React and TypeScript. Apart from the code itself, he is also interested in data structures and algorithms. He believes that development is the most crucial element of a developer’s work, and the best form is sharing knowledge. After hours, he enjoys sports and music.