“It is always important to know when something has reached its end. Closing circles, shutting doors, finishing chapters, it doesn’t matter what we call it; what matters is to leave in the past those moments in life that are over.”
– Paulo Coelho
Dear readers,
As I write this final blog post, I can hardly believe that a year has passed since I started this series. It has been a remarkable journey full of learning and growth, and I am emotional as I reach this milestone.
I hope that this series has been helpful and insightful for you, providing you with a comprehensive understanding of what Software Architects do and their importance in software development. But while this series may be ending, it is not the end of my journey. I am excited to bring you new and exciting content on thecodewolf.in, as I continue to strive forward and bring the best I can to the world.
Thank you for being a part of this journey with me. I look forward to continuing to share my knowledge and insights with you, and I hope that you will join me on the next leg of this journey.
Without further ado, let’s head into the endgame.
Architecture Document
The architecture document is the condensation of the entirety of what we have learnt. It contains functional and non-functional requirements, a technology stack and more.
No development is done before the architecture document and serves as the cornerstone of the entire software development process.
Goal
So what is the goal of the architecture document?
An architecture document:
- Outlines everything from services to technology stack to help developers know what should be developed and how
- It lays out the requirements (functional and non-functional ). This helps in validation with the customer and also have a formal way of interacting with the requirements.
The audience of the Architecture Document
Almost everyone is involved in the architecture document.
These may include:
- Project Managers
- CTO
- QA Leaders
- Developers etc.
For the development team, the document lays out the basic concepts of the system
- Technology stack
- Components
- Services
- Communication
- Etc.
For the management the goals are different. The project manager, CTO and CEO get involved here. They need to know one important thing that “The Project is in Good Hands”
- Requirements should reflect the essence of the system
- Executive summary describes best practices and modern patterns
- Architecture geared towards business goals
In general the Management sections appear first.
The QA Lead should also read this document to prepare the testing infrastructure that depends upon:
- Servers
- Testing tools
- Coding
While many architects might use tools like UML to prepare the document it is advised to use plain English and keep the document as simple as possible.
Document’s Structure
The structure of the document is simple as it consists of the following sections usually:
Background
This is usually a one pager document and the audience for this is the team and management.
This section describes the system from a business point of view.
This also describe:
- The System’s role
- Reasons for replacing the old system
- Expected business impact
Requirements
This section is also a one pager and is meant for the team and management.
There are descriptions needed for two types of requirement.
This needs to be:
- Brief
- Bulleted list
- No more than 3 lines per requirement
The structure is to first include the functional requirements e.g.
Next come the non functional requirements, these should be extremely accurate and specific.
E.g.
Executive Summary
This section is dedicated to the Management and is no more than 3-4 pages long.
This is geared towards the management to understand what all is going on in the Software’s architecture.
We must know that:
- Management is busy and non technical
- Managers will NOT read the whole document ever
The entire goal of the executive summary is to provide high level view of the architecture and help the readers understand the requirements easily.
Some considerations here would be:
- To use charts and diagrams
- Writing it after the rest of the document is written
- Using well known technical terms and jargons sparsely
- Not repeating ourselves
Architecture Overview
The architecture overview is meant for the Development team and QA Lead. It is usually an extensive section lasting for about 10 pages.
This provides a high level view of the architecture and presents the architecture to the team without the need to deep diving to specific components.
This includes:
- General description of the software architecture e.g Web based, micro services, REST API etc.
- High level Diagram
- Diagram walkthrough
- Technology Stack
Components Drill-Down
The length of this particular section can be as long as needed to explain about the components. The audience for the section again remain development team and the QA Lead.
We break down the document role for each component as:
While choosing the technology stack we need to be extremely cautious and specify the rationale for the choice:
Summary
So we have finally arrived at the end. To recap our journey, we have now covered:
Rest assured, this does not mark an end but rather the start of another journey that I as a developer and an author take to strive for my next destination.
Till then, I thank you for being with me and learning with me.
The next blog shall start yet another quest of learning and understanding the ecosystem of Software Industry through our team here at TheCodeWolf.
I keep on coding something cool, visit ankush.tech to see what I am doing!
If you wish to read about my work, here is a book that I published recently – “Knowing Software Architects “
Get Started with CSS today: “CSS Bullets, a comprehensive guide to all the CSS you need!“
Interested in React? Learn react from scratch with my book, “REACT Bullets“.
Not subscribed to the newsletter? Subscribe now!!!
Thanks for sticking around, means a lot!
Leave a Reply