Getting started

Begin by making sure that the team and key stakeholders understand what software architecture is and the value of capturing it in a separate artifact. See Concept: Software Architecture.

After there is agreement that the architectural information should be captured, it is important to come to an agreement on what architectural information you want to capture and what format it should take. Review the Artifact: Architecture Notebook and associated guidance. Agree on what you want to document.

Next, review Concept: Architectural Views and Viewpoints and Concept: Architectural Mechanism. Both are crucial to understanding how to define and communicate the architecture.

Now you can turn your attention to deciding, as a team, how and when the architectural tasks should be performed.

• If you are working on a new project and you are at the beginning of the lifecycle, review Task: Outline the Architecture.
• If you are working on a project that is already underway, take time to document the decisions that have already been made and continue to evolve the architecture as development proceeds. See Task: Refine the Architecture.

Common pitfalls

The architect should not work in isolation and just throw an architectural specification over the wall to the developers. This requires too much documentation and makes it difficult for team members to understand why the architecture needs to work the way it does. Building the architecture is an activity that requires collaboration to be successful.

Avoid creating significant and detailed architectural documentation for agile projects. Don't get caught up in defining exactly what the structure of the Architecture Notebook should be. Focus on capturing the key decisions and the rationale for these decisions. Refer to more detailed documentation where necessary, and don't duplicate material. Keep the documentation clear and concise. Make sure that the people who use the architecture (the development team) are comfortable with the format and content of the architecture. Is there more or different information that they would like to see? Would they like to see less, instead?

Document important decisions. Team members may be close by and you may be in constant contact with them, but teams change and software architects move on to other projects. Failure to document important decisions raises the risk of failure later because future team members won't have the benefit of being involved in today's collaborative decisions. Consider future team members as collaborators that you simply don't have the opportunity to speak to face-to-face.