Getting Started 

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

Once there is agreement that the architecture 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 the Concept: Architectural Views and Viewpoints and Concept: Architectural Mechanisms. 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 some 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 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 consumers of the architecture (the development team) are comfortable with the format and content of the architecture.  Is there more or different information they would like see?  Would they like to see less?

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