A long time reader E-mailed yesterday and gave me this nugget “simple is not always removing documentation.” We actually ended up having a phone conversation about that point, it is interesting.
His initial point was that removing software documentation isn’t in the end simplicity. I agreed with that and point out that my simplicity movement wasn’t about removing documentation it was about reducing the overall complexity of the documentation produced.
Reusable = more simple
The overall complexity of a system should not be a reflection of the complexity of the documentation. In the simple architecture documentation movement we aren’t arguing that people should not have documents rather that the documents should be focused on specific core areas (as outlined in the table here) rather that we logically organize what is documented and which document we put that into.
Its about the logical organization of architectural artifacts. Not the removal of any set of documents simply the proper placement of information into the proper bucket to make that information more useable.
Once the cycle of updating smaller documents with relevant information becomes a core part of the documentation process than the upgrade and future changes becomes just a little bit easier. Trust but verify becomes instead review and continue.
The other side in the end of the movement is the reality of crisis management. If, you have to in a crisis bring in a security expert then your ability as an organization to get that person up to speed quickly is critical. Having a smaller documentation footprint is a quick way to not only create but to bridge that external consultant to external problem solver.
The reusable = more simple phrase resonated with my friend. He hadn’t quite gotten that I wasn’t removing documents but making a more logical document framework. In the end that is the disadvantage of discontiguous blogging. There are a number of pages you have to read to in the end see the whole picture.
It is in the end the little things that matter.
To bring this back to where we started let me clearly call out what the simple architecture movement is in the end all about.
- Not removing documents from an architecture
- Documenting changes between a deployed architecture and the beginning reference architecture (Difference Architectures)
- Putting information in the right document.
- Updating documents so that they are always current
Paul Preiss of IASA posted recently that architecture was a Who not a What. I agree in the broadest sense that software architecture is about the who creates it. But it is in the end also about the next who. The simple architecture movement is about making sure the next Who that creates your architecture can quickly get up to speed regarding what the last Who created. So that you don’t end up with a lot of Who’s asking Who did this!