Technical documentation for software development projects

Why is technical documentation of paramount importance?

Technical documentation is an essential part of the software development process and a software product itself. 

The existence of these kind of materials will drastically improve the solution and brings additional benefits to the development team and project stakeholders such as:

• better communication within the team
• improve team performance and save time
• easier project adoption by project newcomers
• increase project transparency for every stakeholder

In this blog post we aim to share with you the technical documentation our custom software development teams create on each project. To be more specific, what are the purposes for their creation and how do they actually look? So, stay tuned for more!

What does technical documentation include?

Context Diagram

A Context Diagram is the finest tool for describing the high-level view of the system. It will help contextualize the solution rapidly and gain a better understanding of its primary components. 

By creating this diagram we can define the boundary for you between the system and its environment and visually depict how the system interacts with external entities. The latters are systems, organizational groups, external data stores, etc. 

We can also create Context Diagrams in the early stages of development processes to gain consensus on the scope under investigation. Which should be approved by all involved stakeholders and are typically included in the requirement document.

Container Diagram

This diagram describes the all moving parts (containers) of the system. The moving parts indicate - a separate deployable element of the application like a web app, mobile app, backend service, database, object storage, etc. Container Diagram shows how the containers communicate with one another.

Deployment Diagram

This diagram describes how application containers (see container diagram) are mapped to the infrastructure. It contains:

• computing resources: virtual instances, nodes, servers, desktop computers, mobile application
• message brokers: RabbitMQ, ActiveMQ, Kafka, SQS
• storages: relational and non-relational databases, file storages, caching facilities
• infrastructure elements: availability zones, DNS, CDN, Load Balancers, and 
• cloud services like AWS Transcoder or Kinesis

Sequence Diagram

It's a very common case when business processes should be depicted within the entire system. Team members should understand how different moving parts (containers) interact with each other.

The function of such visualisation processes is performed by creating a Sequence Diagram. This type of diagram envisions objects interactions arranged in a time sequence. Sometimes Sequence Diagrams are called Event Diagrams or Event Scenarios.

Vertically the diagram depicts containers that exist at the same time in the system, while horizontal depictions indicate messages exchanging between them. 

Understanding software development effort estimation is also crucial for creating accurate and effective technical documentation for software development projects, ensuring clear communication and efficient project management.

Physical Data Model

One in a list of more powerful tools in the architect's pocket. It describes how entities will appear like in the database management system (DBMS).

The Physical Data Model defines all the relational data models and objects of the database. It enables us to discuss business requirements or new architecture in a much more productive way. 

API (REST) Documentation

It’s impossible to perform integration with some services without an interface description provided. That’s why application programming interface (API) is an essential part of the project documentation. 

The vast majority of modern applications mostly use the REpresentational State Transfer better known as REST for these purposes. It’s a popular approach to creating API’s nowadays.

The most popular form of REST documentation description is called Swagger. It provides possibilities of generating documentation based on the written code and has plenty of integrations in different languages. As a side note, Swagger is also based on the OpenAPI specifications and may be used for the "API first" approach for engaging the contract before implementation starts.

Technical documentation tools 

The most crucial parts of technical documentation are strict and thorough presentation. Axon engineers create architecture documentation by utilizing our best practices and use the following tools:

Lucidchart 

Lucid chart provides the easiest way to create flowchart diagrams. It allows to visualize the network infrastructure, and offers the ability to auto-generate diagrams from AWS, GCP, and Azure networks. 

Swagger Editor

This tool simplifies the process of API design, description and documentation. Swagger Editor provides work in any development environment, validation of syntax for OAS-compliance, and visual rendering of API specifications.

In our next blog post we are going to tell you about unit testing. What exactly is unit testing, why is it needed, and when should it be used? Stay tuned!