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.
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.