How do you use existing solution architecture documentation in your organization?

Harnessing the trove of solution architecture documentation is akin to wielding a compass in uncharted waters. It's not a bureaucratic obligation but a treasure map guiding innovation. I advocate for seeing documentation not as a static archive but as a dynamic force propelling projects forward. These documents aren't relics; they're the living chronicles of lessons learned, architectural choices, and strategic insights. By tapping into this reservoir, architects don't just decode the past; they amplify the present and sculpt the future. It's a journey where documentation isn't a formality; it's the wind beneath the wings of agile, informed, and visionary architecture, transforming a mere record into a catalyst for perpetual innovation.

With people changing groups or companies , it's also important that a proper handover is done to someone who has some historical background about existing architecture and why some of the architectural decisions were taken. It's important to have a blue print with the process flow and a high level design document that describes each process flow. Sometimes a decision was probably made due to lack of new technology at that time and other time the decision was probably made based on limitations from a dependent system within the flow.

We refer to existing architecture docs as a blueprint for new projects. They help in understanding what worked well and what didn't. This way, we don't reinvent the wheel and ensure best practices are followed. They also help onboard new team members quickly.

Having your solution architecture properly documented helps avoid trouble in the future. Clearly explained requirements, the thought process behind it, and the components involved gives current and new employees an easy way to understand how all of it works. Having those in mind, the architecture can be discussed, analyzed, and improved with great ease and precision, without the worry of breaking the same.

It is helpful to use existing documentation in many ways. 1. Existing documentation captures the knowledge and decisions made during the initial phases of the project. 2. New team members can quickly familiarize themselves with the solution architecture by referring to existing documentation. 3. Using established documentation ensures consistency in design principles, patterns, and standards across the project. 4. Existing documentation provides a baseline for understanding the current state of the architecture. 5. Documentation serves as a historical record of decisions made during the architecture development process.

Existing documents are very helpful to understand the current designs and principal your organisation is following. These documents can give you insights of existing patterns, reusable component information and also what are the measures put around networks, security, risks and other factors. When you refer to existing documents, one of the important aspects is to make sure that the document is current and contains relevant information. If you refer to an old document which is outdated, it could provide wrong information which could lead to bias and add unwanted assumptions and prospectives.

Benefits of Documentation: Quality and Consistency: Ensures a consistent and high-quality approach across solutions. Risk Reduction: Minimizes errors and misunderstandings by clearly documenting decisions and processes. Enhanced Collaboration: Improves communication and collaboration among stakeholders. Reusability: Facilitates the reuse and adaptation of components by detailing dependencies and interfaces. Maintenance and Evolution: Supports ongoing maintenance and evolution by documenting the current state, design rationale, and assumptions.

Documentation is time consuming and often overlooked or lost over the period due to people not referring it or mishandling it. It’s good practice to maintain it in all respects is possible. Good practice is document the code at granular level and generate api version documents from code like Java docs or any other tool available. Try to update high level and low level documents with every production release. JIRA is good tracker and helps in documentation as we go along. Its integration with google docs,slack,quip,jamboard and ci/cd platforms helps a lot in documenting release cycle.

The shift-left and Everything as a code practices have influence every part of the software development lifecycle. Similarly the architecture needs to move closer to the actual code itself, and evolve as the code and teams change. So, tools like acceptance tests and Compliance as a Code are applied techniques to ensure the architecture is evolving the same as the application is. In addition, standardisation tools like OpenAPi and keeping an updated event catalogue, makes the documentation of the architecture approach on how the systems integrate and communicate always updated.

In addition, Solution Architecture documentation also helps to: 1.- Support and visualize how the technology is aligned with the business needs. Each component would be aligned with design principles, business requirements, policies etc. 2.- Have a set of pre-defined artifacts to be developed as part of the solution architecture, would help to estimate effort and cost during concept engineering phase.

Once you realize that the existing architecture is outdated and the initiative people that built it had left, it is hard to maintain the update that has been implemented. You need to revisit all components and write down changes. Also re-document actual usage of each module. You should tell what are no longer existing components and add new ones. Also start designing new architecture diagrams to perfectly represent it. Moreover, you could start writing suggestions and enhancements on the fresh model.

Often the adopted strategy is document from beginning of project and update documentation as much as we can with every release. (issues fixed, new functionality, version,branch,major/minor for layers touched from top to bottom level of repo ). Have a high level view of the architecture updated with each release. Usually have a doc/readme file will be a good placeholder. Often these things are missed out due reasons mentioned which leads to sphagetti system. When people leave have a TOT recorded for as is state.

There's a great metric that can be implemented, calculating the time distance an architecture document in your organization stays relevant. In my experience, the root cause of every challenge in architecture documentation has been that the Architecture is not being part of the software delivery loop. The way that this can be solved is to adopt an "Architecture as a Code" approach through translating the Architecture NFRs into acceptance and compliance as a code tests. This way, you can monitor and enforce the architecture description and NFRs to always be updates, as the tests will be part of the continuous delivery pipeline.

While using existing solution architecture documentation provides numerous benefits, there are also some challenges associated with this approach. Documentation often requires ongoing maintenance, but it may be neglected over time and due to the reason documentation may become outdated as the project evolves or undergoes changes or may be incomplete, missing critical details or changes made during the development process. Different versions of documentation or documents created by different team members may exhibit inconsistencies. The availability of key individuals who created the documentation may be limited, leading to a dependency on specific team members.

Solution architecture documents play a crucial role in the corporate knowledge base. These documents should provide a bird's-eye view of the systems in scope, clearly outlining essential app components, data architecture, change processes, integration points, as well as security and governance-related details. The key element is that architecture documents must be living documents. Stale documents are counterproductive. Therefore, it is imperative to periodically discuss and communicate the architecture across relevant stakeholders and development teams.

In my experience, the architecture should describe the What and Whys and the NFRs of the "how" of the software delivery. A great way to enforce that is by adopting, what I call, "Architecture as a Code". A code-driven architecture can be implemented by adopting acceptance tests that implement the NFRs, Compliance as a Code that test the platform assumptions of the architect, and have an updated event catalogue that keeps an updated documentation of what system speaks with what and on which use cases through what data payloads. Adding Compliance as a code, acceptance tests and data-catalogue as part of your software delivery loop, it will guarantee that the architecture NFRs are always up to date with what's delivered, and what's expected.

To maximize the value of existing solution architecture documentation, regular training sessions and knowledge-sharing meetings can be conducted. This helps ensure that all team members are familiar with the documentation, understand how to use it effectively, and can contribute to its continuous improvement. Encouraging a culture of documentation and knowledge sharing fosters collaboration and ensures that the documentation remains a living, useful resource.

Tools like javadocs ,docgen, and various maven plugin helps in generating the api documentation. Jamboard, slack, google docs/quip , sharpoint repo, jira or anyother collaborative tool,document templates, CICD tools (cloud or in house) , GIT/SVN repo. Branch.

In my view to do proper documentation at every stage of the solutioning we should follow the proper framework such as TOGAF. Adopt standardized templates for documenting different aspects of the solution architecture, ensuring consistency across documents. Implement version control mechanisms to track changes, updates, and revisions to the documentation.

Software Intelligence tools can be used to automatically create a living knowledge base of the application architecture from the semantic analysis of the source code, this removes the dependency on developers to maintain the documentation.

Agreed. One of the biggest time-savers of Gen AI is to create all the artifacts - ERDs, tech stack definitions, sequence diagrams - and then maintain it. Bonus: With some tuning you'll achieve a standard taxonomy across architectures, apps and knowledge bases.

Consider the following; implement a fit-function on how updated your architecture NFRs are. Then try to implement acceptance tests and compliance as a code to keep track the defined architecture NFRs. I bet you that you will see an improvement in your fit-function, whereby your "as a code" defined NFRs will be updated as the software changes are being delivered.