How to decide on architecture for your company, with no fear — part 3
In the previous part, I wrote about the considerations I took in choosing the technologies and why the considerations are not only technological but also depend on the people who will use these technologies.
In this article, I will detail how I wrote the architecture document, what was done with this document, and what was done after publishing it to the stakeholders.
Writing a clear architectural document
So after I have decided on a technology stack that is right for the organization, it is time to write clearly and simply a document that details it and explains the technology choices.
The main emphasis in an architecture document is its simplicity. Every developer who works in the organization now, and developers who will join in the future, should understand from this document what technologies the organization works with, what the considerations for selection are, and what the general technological plan is in the organization.
Purpose & motivation
In the first part of the document, I opened with a general explanation of the purpose of the document and the importance of the document for the organization. As part of this explanation, I also detailed the motivation for the architecture document, why it is important to establish it in the current organization, and what problems it solves.
Such an introduction will help the reader understand what he is getting into and help mobilize him to understand the importance of the chosen technologies, even if he arrives without a background in them.
This document provides an architectural overview of the system.
It is intended to capture and convey the significant architectural decisions which have been made on the system.Here are some key requirements and system constraints that have a significant bearing on the architecture:
- Develop high-end frontend apps for the organization, using cutting-edge technologies
- Improve the organization’s frontend clients experience
- Replace all organization’s frontend apps with new ReactJS apps, served with Server Side Rendering using NextJS
- Align all technological stack across the organization’s Frontend project apps
- Prevent technological overload
- Increase the organization’s Frontend unit testing coverage, and code reliability
- Increase project apps readability for the organization developers
- Allow the organization developers mobility & support across all Frontend apps
Technology
I have divided the technological part of the document into several sections according to the technological parts of which the system is composed.
The architecture I wrote was for frontend, so the technological division I chose was: backend-for-frontend, scripting language, styling, and testing.
In each of the parts, I have indicated the chosen technology by name, a link to the main website of the technology where documentation can be found, and an explanation of why this technology was chosen and why it is suitable for the organization in the long term.
In my opinion, it is important not to make deep comparisons with other technologies in the architecture document. It will add a lot of content and may reopen a discussion about the correctness of the choices made. It should be specified what was chosen, and not why other technologies were not chosen.
Think positive :)
The technological part, although it is the heart of the document and the most important part, is the simplest. It will only have a breakdown of the technologies that will be used, a brief explanation of each of them, and that’s it. No need to dwell on this part too much. The decisions were made, and this is the result.
This is an example of a design section I wrote in one of my architecture documents:
Out of consideration for performance requirements, there is a preference for using traditional CSS over CSS-in-js in the overall page design by the developers, to enable CSS caching in the client’s browser.
The leading solutions in the market for implementing CSS are writing traditional CSS, CSS modules, Styled-components, and TailwindCSS.
To maintain the balance between learning curve, site performance, out-of-the-box responsiveness and technological advancement, TailwindCSS provides the appropriate technological response, and also a widely used library with great support from the developer community.
Project structure
Another section that I think is very important to include in the document is the project structure.
In order to prevent file chaos, and each developer will decide on the convenient way for him to save his files and directory structure, I added a section that defines the directory and file structure in the project, which the developers are required to implement.
By defining a clear structure, the project is clearer for everyone to read and understand.
For example, this is how a project structure definition looks like in a document:
project root
│ 📄 README.md
│ 📄 package.json
│
└───📁 apps
│ └───📁 app1
│ │ │ .babelrc
│ │ │ .browserslistrc
│ │ │ .eslintrc.json
│ │ │ 📄 jest.config.json
│ │ │ 📄 tsconfig.app.json
│ │ │ 📄 tsconfig.json
│ │ │ 📄 tsconfig.spec.json
│ │ └────📁 src
│ │
│ └───📁 app2
│ └───📁 app3
│
└───📁 libs
└───📁 lib1
└───📁 lib2
A quick short explanation to each of the strucutre parts can also be added, to help the reader understand the purpose of each folder/file.
Coding standards & best practices
The last part of the architecture document defines standards and best practices for writing code. This section is complementary to the previous section and defines for developers how to write their code uniformly.
The specification of the standards can be part of the architecture document itself or be a separate document.
I prefer to separate the definition of the standards into a separate document that will be available and easy to read by the developers regardless of the entire architecture, and in this section, give a link to the document.
The definitions of the standards for writing code should be quite detailed, so a separate document would be correct here.
In case you decide to use predefined market standards (AirBnB, Google, etc.), and there is already a detailed document online, this is the place to give a link to read this document.
Last but not least…
The last thing in the document seems small and marginal, but in my opinion, it is very important; it is the signature of the author of the document, a contact form, and the date of its last update.
If anyone has questions or suggestions, it is important to leave contact details and the validity of the document. This short line can prevent misunderstandings and the use of old versions of the document.
Document last updated on 10/1/2023 by Erez Carmel
What do we do with the document?
Now that our architecture document is ready, it’s important to distribute it correctly, to reach all of its stakeholders, from the development managers to the last developers.
The distribution of the document is the stage in which we do public relations for the new architecture, and ourselves as the ones who made the final decisions.
I prefer to prepare a presentation and arrange with the developers for a presentation in which I will convey to them the main highlights of the document, and they will have the opportunity to ask questions and have an open dialogue about the decision-making process and their concerns about the technological changes.
As I wrote in part 2, the developers are human, they have development habits, and now we change it for them. It is important to be attentive to their concerns, give them help and solutions, and accompany them in the process.
In this way, we will also receive more trust from the developers, and we will also achieve the desired result: correct implementation of the new architecture.
In addition, for developers, it is important to explain the architecture to managers and decision-makers, and through a correct and direct presentation, we can gain support and trust in the technological change process.
Example architecture document
As promised, here is an example of an architecture document template that I made for you. In this document, you’ll find the structure I detailed, and in my opinion, it is the easiest to understand by both developers, managers, and other stakeholders.
Some might think that, at this point, the architecture implementation is done. I think they are wrong.
As architects, we are not only responsible for defining the architecture but also for building an ecosystem to support it in the long term.
In the next article, I will talk about what are the next steps after the architecture document was published. What do we need to do to support our architecture implementation for the long term, how to form an architecture team, and what are its responsibilities.
Stay tuned…
That’s all for today, let me know what you think. See you on part 4, which will be the last of my How to decide on architecture for your company, with no fear article series.
Happy coding! 🤓
