- Document only small slices of the system one at a time at the time you need them
- Be as specific as you need without going into too much details
A typical business system, one that is software intensive, is a really big and complex. When developing one such system it is impossible to document everything at once. What I do is to create a general corner stone architectural specification that defines the core architectural areas and principles of the system, a reference architecture around everything will be build and then create a series of small architecture documents (Architectural Notes or Memos) which are slices of architecture targeted at a specific system view or functionality which is developed for a first type. Architecture is a generalized specialization so such documents must convein all the information one needs to implement the designed architecture but not specialized too much in order prevent the multiple variants the same architectural areas can have.
It is important not to design to early , but at just the right time. The goal is reduce the amount of time passed between the design creation and the implementation and to focus the architectural effort on the architecture which is need right at this moment of the currently developed sprint.
Designing and documenting and architecture slice is one part of the whole problem, even when you create such a design at the right time with the right amount of detail the majority of the subsequent effort is spent communicating and reviewing the architectural implementation. If the implementation part is done by the architect and the senior team (such as the core of the system) a significant part of the architects effort is spent disemminating through the development team (or teams) the culture and the ideas required by the architecture design.
Software is plastic, and programming is flexible. Event the most pure architecture can be twisted, scratched and mutated in something recognizable. The best way to insure an architecture to survive is to set up much of its essence in code and build tools which guide the developer down to a certain way of solving problems (which has its own problems , which is why architecture should be approached slice by slice and nothing is one hundred percent fixed in stone and unchangeable) and to integrate its core principles into the development culture of the development team which will ensure it gets adopted by every new team member.
Lots of teams make use of the shared tribal team identity as the only reference how things should be done by the project. This practice is spurned by software engineers, and with good reason, because software cannot be developed with tribal memory and shared culture alone, documentation must exists, tests and build tools must exists in order too enhance the human falabilities to which we all are susceptible : short memory, illness, death, holidays and leaving for a better opportunity. In its essence agile development values people over processes and interaction over rules, it doesn't mean no documentation or processes should be in place. We all are humans, and by definition fallible. Agile architecture should strive to reduce the human error by documenting and the essence of small specific slice of the system such as : grid architecture, background process architecture, form architecture, repository architecture, commenting system architecture etc.
Short is better for software developers, people will more eagerly read a ten page document then a one hundred page document. They will read it more often and learn more from it. It is also really easy to communicate a short document then a large one. Also, less errors are introduced in a short design then in a large one.
The agile manifesto reads as follows:
Individuals and interactions over processes and toolsWorking software over comprehensive documentationCustomer collaboration over contract negotiationResponding to change over following a plan
The agile manifesto clearly indicates that things on the left are more valuable then things on the right, but things on the right have a value. They are second to the things on the left, people have more value to software development over processes and tools, working software is king over documentation. But a balance must be made, without a documentation who will understand what is being developed? Without a set of class diagrams that show the core architecture for a subsystem from top to down and text describing it who will understand the code without someone guiding him through?
Each day when I start my work I say to my self :
Your job is to enable other people to do their job better
I'm a technician and my focus is technology and the development team that works with it. I'm a software engineer by trade and a craftsman by soul and I really think only three things are important in software development:
working software, people and communication
For me agile architecture is that which maximizes those three things.
