Architectural Documentation Guide: Who and When

In the previous article, we discussed basic architecture document types that can be used to document a project. If you missed the previous article, I encourage you to read it before continuing.

We already defined with you that we need architectural documentation for different purposes like knowledge sharing, communication, and analysis. It will help the team and new members to understand architecture, communicate with stakeholders, and make it easier to review architecture in the future. Now it is time to clarify who is responsible for specific documents and when we should them.

It’s pretty clear that small projects may not need a lot of documentation, while medium and large projects may require a lot of documentation. So first of all, let's discuss project sizing.

Project Sizing

Understanding of project size is very important for effectively using our time and resources during documentation creation. There are several software project sizing methods:

1. Function Point Analysis (FPA). This method measures software size based on the functionality provided to the user.
2. Lines of Code (LOC). This method measures software size based on the number of lines of code written.
3. Story Points. This method measures software size based on the complexity of the work to be done.

The exact metrics and size classifications can vary depending on the specific method being used, but these are a few common examples. Note that the LOC method cannot be used during the investigation stage. There is a lot of information, pros, and cons that can be shared about these approaches, but it will be a topic for a different article.

For now, let's simplify this and imagine 4 possible project sizes:

1. Micro. One small team (up to 5 FTE), less than 1 month duration.

We do not need any documentation here, but if it is possible, it would be good to document decisions and general structure in High-Level Design.

1. Small. One team (up to 10 FTE), few months duration.

Similarly to Micro projects, we do not need a lot of documentation here, but High-Level Design should contain assumptions, research items, options, and some diagrams. It should also contain open questions, tech debts, etc. In a few words, after reading this document, we should comprehend the whole situation with the project.

1. Medium. One medium team (up to 20 FTE), few months duration.

All documentation we mentioned earlier is required.

1. Large. Several projects, several streams.

All documentation we mentioned earlier is required.

Note: FTE (“full-time equivalent”) - it refers to the number of hours worked by a single employee in a week.

Documentation

Intro

Before all, you should understand that there is no one source of truth about technical documentation. When choosing documents to be created, format, diagrams, you should always understand why you need this and who stakeholders are. Also, you should understand timelines, team capacity, and project requirements, because for large projects for big corporations we may require to create the documents according to specific standards, while for another medium or large project it will be enough to create documentation without strictly following all the rules.

High-Level Design (HLD)

As we already know, this is a high-level description of proposed architecture. In the case of a micro project, we may skip this document or use it to highlight key decisions, assumptions, and other information. For other project sizes, this document is used to describe a specific epic or feature.

Who: This document is created by an?architect?and then used by a?development team. A?tech lead?can also update it. When the project doesn't have an architect or the architect is only partially allocated, the tech lead will be responsible for most of the HLD.

When: Usually, it is created before feature, epic, or micro project start during the planning phase. Then, it can be updated if something changes, but in a perfect world, there shouldn't be significant changes that may impact this document.

Solution Architecture Document (SAD)

This document should be created for the whole project to describe technical solutions. It is used to present this solution to stakeholders, provide a general view of the solution for further development and testing, and more. In most cases, this document is required for all project sizes.

Who: Similar to HLD, this document is created and managed by an?architect. For small projects, the?tech lead?will be responsible for this.

When: It should be created before the project starts and can be updated during the whole project. Usually, it is done once per some period, like release or sprint. It depends on the specific project and timelines.

Technical Design Document (TDD)

This is the most technical and low-level document that contains information about the final system design and implementation. This document is created for each epic or for the whole project if it is small.

Who: It is created by a?tech lead, but some parts can be filled in by other team members who can describe implementation details. An architect reviews and validates this document.

When: The TDD is created when an epic or a small project starts in the planning phase of the sprint. It is updated during development according to the taken decisions and should be finalized at the end of the sprint or small project.

Architecture Design Decision (ADD) and Key Design Decision (KDD)

We already know that these documents are pretty similar, but ADD is more technical and should contain architecture-specific details.

Who: It is the?architect's?responsibility to create and support these documents. It is also important to consult with the?tech lead?all the way to make sure all the decisions are clear for the development team. Usually, we create a separate document for each global decision and point them in the SAD. If there is no full-time architect on the project, the?tech lead?takes responsibility for these documents. It may not be very detailed, but it should give an idea and reasons for such decisions for the team and help in the future to answer team’s questions about project development.

When: These documents are not necessary for micro projects. Usually, I use HLD for micro and some small projects to document the decisions. In all other cases, this document should be created once global decisions occur. It is better to get all the decisions before the development stage during planning and designing the architecture of the system. In some cases, such decisions may occur during the development phase, so they should be documented as soon as possible. All the documents should be reviewed and finalized at the end of the sprint or the whole project.

Documentation map

To have a quick hint about what documentation we need for each size of project, let’s create a simple table:

Conclusion

In conclusion, effective documentation is crucial for any software project. By following guidelines, software teams can ensure that their projects are well-documented and successful. It is also important to remember that a lot depends on the project size, team composition, and timelines. From the other side, we haven’t discussed each of the documents in detail, necessary diagrams, documentation style, etc. But it will be covered in the next articles. So be careful when choosing the list of necessary documentation to balance time spent and profit gained from created documentation.