What are the best practices for documenting system architecture evolution?

Formal Representation: Provide a standardized way to model and describe system architectures using formal notations. Communication and Collaboration: Facilitate clear communication and understanding among stakeholders (architects, developers, testers, etc.). Analysis and Verification: Enable early analysis of architecture designs for potential issues, inconsistencies, or violations of requirements. Documentation and Maintenance: Create comprehensive and maintainable documentation of system architectures, supporting evolution and change management. Structure: Describe the components of a system, their relationships, and overall organization. Behavior: Represent the dynamic aspects of a system, interactions, com patterns, and state changes.

Use an architecture description language (ADL): Why: Think of it as using a special language to tell the story of how our system is built. It makes sure everyone understands the details in the same way. Benefits: Helps us communicate better, makes our plans clear, and ensures everyone is on the same page. Consistency: Keeps our story organized and avoids confusion.

La utilización de patrones de dise?o solidos y correctamente seleccionados. Considerando criterios como: el tama?o de las aplicaciones, el flujo de información y necesidades de procesamiento. Lo importante es procurar que las aplicaciones se apaguen a patrones de común conocimiento dentro de la organización de tal manera que ante la necesidad de una variación solo se documente en un solo lugar.

Die Rückverfolgbarkeit (Traceability) von Anforderungen, Umsetzungen und Tests unterschiedlichster Ebenen ist zwingend notwendig, um bspw. ?nderungshistorien, Gesetzeserfüllungen Vollst?ndigkeit nachzuweisen.

Maintain traceability and rationale: Why: We write down why we make certain decisions and connect the dots between our ideas, plans, and what we actually build. Benefits: Helps us remember why we chose a particular path, makes it easier to fix things if something goes wrong, and guides future decisions. Consistency: Keeps our story coherent and logical.

Traceability or as we call it, audit trail or as some folks call it revision history is very important when you want to track evolution of your system. Many times I have joined a project which is already underway and when I see a module or a feature, the question that comes to mind, is how did this come to be? or, why was this added that is where version revision plays a pivotal role. Say you moved from a pull based to a push based architecture for a feature.. a revision history with proper background, jira details, meeting links, ADL diagrams, helps a new joiner easily navigate the complex architecture. to summarise, we need to have traceability of "what" was changed and "why" it was changed

Apply version control and configuration management: Why: It's like having a history book for our system, showing all the changes over time, and keeping different versions organized. Benefits: Makes it easy to work together, allows us to go back in time if needed, and keeps our story well-ordered. Consistency: Prevents conflicts and ensures we all know which chapter we're on.

VC Tracks and manages changes to system arc artifacts (documents, diagrams, models, code) over time. Stores multiple versions of artifacts. Allows comparison of different versions. Enables rollback to previous versions if needed. Facilitates collaboration among contributors. Git: Distributed version control system widely used for development. SVN (Subversion): Centralized version control system. Mercurial: A distributed version control system. CM Identifies, organizes, and controls the configurations of system architecture artifacts and their relationships. CMDB ( Database): Stores configuration information and relationships. Ansible: CM tool for automating deployments and configuration changes. Chef: CM tool for infrastructure automation.

Use views and viewpoints: Why: Imagine telling the same story from different angles. Views help us see the system in different ways depending on who's listening. Benefits: Lets us share the right details with the right people, ensures everyone's needs are considered, and keeps our story rich and varied. Consistency: Keeps our story interesting without overwhelming anyone.

To enhance your documentation, consider including: 1. Architecture diagrams. 2. Documenting decision context. 3. Providing training and onboarding materials. Architecture diagrams visually represent the system at different stages and can be created using tools like draw.io or Lucidchart. Documenting decision context provides insight into the rationale behind architectural choices, including constraints, trade-offs, and alternatives considered. Use architecture documentation as a basis for training and onboarding new team members.

The description of current state should be brief but understandable. It should in include architectural decisions rather technological choices. e.g. we need an API gateway to scale to higher loads without requiring additional hardware for every x amount of increase in throughput. Now developers can decide if they want to use reactive paradigm like NodeJS, Micronaut, Spring cloud gateway or some custom implementation based on underlying complexity.

Update and review your documentation regularly: Why: Our story is always evolving, and we want our documentation to keep up. Regular check-ins make sure we don't miss any exciting twists and turns. Benefits: Helps us stay current, prevents our story from becoming outdated, and guides us in making the right choices. Consistency: Keeps our story reliable and trustworthy.

Why: Life is full of surprises, and so is technology. We want to make sure our story is ready for whatever comes next, whether it's growth, challenges, or new tech trends. Benefits: Keeps our story relevant and adaptable, helping us face the future with confidence. Consistency: Makes our story flexible and future-proof.

In every project i was a part of documentation was always a sore point as no one actually LIKES doing it. dont be rigourous about the form, capture the the data in the process and find a way for your team and describe how its documented. Do NOT copy another company/division or take a bought system straight off, it will be a waste of time.

Develop effective architecture principles. Enterprise principles provide a high-level set of guidelines for designing and implementing enterprise solutions. Enterprise principles guide decision making throughout the organisation, while Architecture principles are specific to the design and implementation of the enterprise architecture. Principles for each of the four architecture domains: business, application, data, and technology can be formed using a Principles catalog - Artifact (TOGAF ADM) Both types of principles are important for effective enterprise architecture governance and decision-making as they reflect a level of consensus among the various elements of the enterprise, and form the basis for making future IT decisions.