You organization might have Technology Strategy, Technology Guidelines, Product standards, Product strategy. Each product or set of products might have architecture guidelines. You must ensure that your architecture is in line with those strategies and guidelines.
According to the guidelines you prepare a document that represents all the concepts, the problem, the available solutions, the trade-offs and risks, the design of each solution, the execution plan in detail. You can name it as Architecture Concept Document. It's a living document and should capture the current status of the software architecture.
After you have taken the decision and defined the detail architecture, you create a Software Specification Document(SSD). And according to the SSD the development can start. During development you will come across issues that will result in adapting and refining the Architecture Concept Document. Thus, the Architecture is only final before you release your product. Even after that, during the maintenance period you might do major changes or add functionality. This should result in a change in architecture. You need to capture this in the architecture, otherwise your architecture becomes obsolete over time. You could maintain the document with versions. The versions before release, the final release version and the versions after release. You can prepare a short document that describes only the architecture of the finalized version for the product in another document as a bluebook.
Preparing an ACD is not the end of work for an architect, he needs to help forming teams who will implement the architecture according to the work package. He needs to outline the dependencies between the work packages or teams. He can also help provide an effort estimate and identify the skills needed for implementation. He often needs to lead various Proof of Concepts(PoCs) needs to be done.
What information should you write in that document? Here I will discuss what topics you can include in the document.
Summary
describe what the reader should expect and how the information is divided into chapters and which chapter explain what.
Preface section
The context - business and technical context that describes why you're doing this
Stakeholders involved and their role -
The Architecture drivers - as discussed above the inputs that make consolidates the problem space and the current status in brief.
The decisions status - that have been taken in each step as a versioned update.
The current status - of the architecture
Introduction section
Details of Inputs
Business goals
Derived requirements from the goals and from stakeholders
Quality - quality attributes considered and what extend they are going to be implemented, any trade-offs among then, standard and guidelines followed
Available technology - what are the existing technology or product or external services you are going to use.
Architecture Drivers - as discussed above the inputs that consolidate the problem space. Why you considered them and their impact on the decision
Boundary conditions
Scope
Assumptions
Overview Section
Present the architecture diagrams and Describe them. First present a high level architecture, then elaborate each section with diagrams as needed. Make sure readers can connect to the high level architecture when they read the detail architecture.
Decision section
The trade-offs and risks of each solution
The challenges of each solution
The decision taken in favour of a particular solution and why, what could be the impact if risks arise
Any decision taken on technology that will be used
Reuse of existing component section
Details of each internal or external component or services user or reused how they are used in which part of the architecture and why, the benefits and drawbacks.
Integration section
How other software or service can integrate with the product, if applicable an APIs and their details.
Security section
How Data privacy is ensured
How protection different attacks are ensured
Deployment, Migration ,Operation
How to deploy, what infrastructure to use, if any configuration needed to deploy in different infrastructure, what the hardware systems and details, any minimum requirement or type of hardware requirement
How to migrate to other environment if needed
How to operate the productive and test environment
Testing
What to test, how to test, who will test, the test strategy, what are the acceptance criteria of end to end test and user acceptance test and how to perform them.
Summary
A short summary to understand the gist without reading the whole document.
References
A references section is the last section of document that's been written. It lists all the sources you've used, so readers can easily find what you've cited.
Glossary
A glossary is an alphabetical list of terms and their definitions found in documentation relating to a specific subject. They usually occur after the body of the document.
Appendix
A section at the end of the document that includes information that is too detailed for the text of the document.
Comments