How can clear architecture documentation help you avoid costly mistakes in application development?

Codebases contain huge number of code lines. Undrestanding the whole system without documentation is a challenging task. But with documents you can undrestand the whole syatem easily. The only caviat of having document is that document itself becomes obsolete over the time so it's necessary to keep your documents up to date.

The key is to document at the right abstraction level and to document the rationale. It will help people to understand the system. The code at the end of the day will be the truth.

It’s absolutely essential to document, for a number of reasons: 1. Initial proposal to the rest of the team - this helps everyone communicate in a real world way, without needing to dive into the actual code, which is time consuming and sometimes difficult for people who may be at a 10k foot level and not ready/able to clone the repo and open an editor 2. Reference for task management - initial architecture documents will drive task breakdown and ultimately workflow and priority order, all of which enable teams to focus on items autonomously and also provide metrics for seeing team efficiency and therefore being able to tease out roadblocks, slow points, etc, so that they can be removed for developer ease 3. Onboarding! - crucial!

As the application evolves so does the team, with old team members moving to other projects, teams or companies and new members moving in to the team. Architectural documentation helps to quickly train new team members and helps in understand a technical flow saving time and energy and more importantly avoiding reworks. As we all know any mistake in SDLC during the later phase is too costly to fix and a correct Architectural documentation definitely helps to avoid such mistakes if people have clear understanding of flow to identify, fix or even make the system more efficient.

While the system documentation mostly considers how a specific system works, and how to work with it, good architecture documentation provides a clear picture of why a set of systems behave and interact in a specific way. Examples: Why does it lean on an event driven architecture instead of synchronous apis? Why are certain functions contained into one common service, while others are split into microservices? Why do we store this data in an intermediate step, while some other piece of data in handled in-memory and only stored when processing is complete? Which part of the system is responsible for synchronization of state?

Without clear architecture documentation it's not possible to identify underlying bottlenecks and embrace best practices to resolve issues.It helps to establish common language among development team and operations and also minimize person dependency for particular solutions.

It definitely helps in establishing better communication and collaboration among the various teams - devs, QAs, and product. And it helps in knowledge sharing. It can be used to show why a particular design is adopted. It defines clear boundaries and aids us to follow the standards and best practices.

Maintaining the architecture documents and keeping it updated is perhaps, not as charming as developing a new system or writing a brilliant piece of code. I found people are reluctant to keep documents updated, this is the last things to pay attention for many of the projects I involved. And apparently and usually there is no immediate rewards for keeping the documents updated. But, what we often forgot, maitaing the documents is actually the hygiene. I have seen many incidents and major disasters during transformation projects, during simple changes, just because the baseline was not properly documented.

Architecture documentation is important when systems start to be complex. You can make the parallel with cities. A city with proper urbanisation planning, guidelines, patterns and norms will result in a city efficiently managed. Take the example of Singapore. On the contrary, a city without any design planning and rules will turn into chaos such as some cities across the world.

Architecture documentation is helpful to keep focused on how something is to be built, especially in longer projects. Over time and if the documentation is updated frequently, it can assist in troubleshoot bottle necks, identify security risks, or help prioritizing updates to the system that the architecture is referring to.

Measure it. Similar to development measuring code-churn to understand if the code is maintainable and clean, so should architecture documentation be measured for churn. If the documentation is outdated, needing continuous changes when components change, etc. it is sign of architecture-smell that the documentation is not clear/clean. Clear architecture documentation should be simple, concise, and outline domain responsibilities and dependencies within the system.

Incorporating User Stories or Use Cases into your architecture documentation can significantly enhance its clarity and usefulness. User stories help in illustrating how different components of your architecture interact to fulfill specific user needs or business requirements. By embedding these narratives, you provide real-world contexts to the architectural elements, making it easier for stakeholders, including developers, testers, and business teams, to understand the architecture's practical implications.

Most organzations aren't investing in formal architecture teams, making tooling a challenge. The days of RUP are gone and most teams don't exercise standards like UML; they use parts of UML, but not to the level to get real benefit. Agile architecture and cocktail napkin diagrams are most common. As much as I prefer modeling, most contemporary architecture is based on diagramming. To that end, any diagramming tool will be sufficient with defined standards. I've delivered architecture views in PowerPoint. Confluence, with its diagramming plug ins, is fairly ubiquitous and supports both collaboration and linking. Stay away from document based diagramming (e.g. emailing documents) as version control is a real problem. Centralize!

Part of a clear architecture is communicating not only the business value of an architecture design but also an understanding of why. Delivery teams will tend to follow the existing design patterns and architecture of the system being changed. They will often ignore the new design unless they understand the why/value behind it. They don't see the "big picture". As architects it is our responsibility to communicate it.

1. Start with the audience. Not just roles and personas, but specific people that you know will consume this information. 2. Write down the questions that the document should answer. 3. Validate with your audience that these are indeed questions that is worthwhile answering. 4. Decide which views will require regular updates, and try to automate (using structured repositories and tools) as much as possible to generate these views. 5. Develop a weaving narrative that connects views to concerns, requirements to needs, recommendations to rationales. This is where the true value is.

The following architecture documents are essential for software development projects: -Architecture, components, modules and interfaces diagrams. -Coding standards, design patterns definition. -Security and disaster recovery documentation.

Some of the key documents I kickstart on my first week as an Architect: 1. Architecture Runway: If you are a solution architect working on an Agile project this is going to be your north star. Identify the key decisions which the project/program need to make and plot it on a time line. Iterate over it and get an agreement from your stakeholders and you have your workplan ready for each sprint. 2. Non Functional Requirements and how to Test them 3. Architecture Decision Register 4. Principles and Patterns There are various other architecture artefacts like Roadmaps, Options Assessments, Solution Architecture Documents etc. However if you ask me the value for every ounce of ink I will rate the first few much higher.

1. Gregor Hohpe: The Software Architecture elevator 2. 97 Things every Software Architect should know 3. Documenting Software Architectures Views and Beyond. 4. Technology Strategy Patterns These are useful books but you can't learn swimming by reading books. You learn Architecture by doing it.

Great, if anyone can contribute /discuss on the available tools for the architecture documentations and their corresponding strengths and weakness.

Commenting each line of code appropriately is crucial for both short and long-term benefits. It enhances understanding, facilitating quick issue resolution and effective collaboration. In the long run, comments aid in maintaining and updating code, especially in team settings or when transferring projects. Well-commented code becomes a valuable resource, reducing onboarding time for new developers and ensuring consistent knowledge transfer, thereby boosting overall efficiency and productivity in the software development lifecycle.