Last friendly blog before, well you know.

Primary Menu

Once upon a time we documented everything. Now we can’t find the time to fix all the documents.

Your system is in an error state. One of the things that I find interesting when over the years I have had conflicts with people, is the reality of an error state. It took me a long time to realize that you have to understand the person you are talking to, before you decide to reveal that you made a mistake. Some people will look at you and say “it happens, move on.” Other’s will say nothing but hold it against you. Lastly there are those who will perceive that as a weakness to be exploited and used later on. So you have to be careful. Know your audience before revealing mistakes. That said everyone makes mistakes. From spilling coffee on a table to a glaring horrible mistake on your submitted taxes, we all make mistakes. We all wish we could pull them back with some sort of magic spell. Just make that mistake go away.

The reality of the world isn’t the mistake however. Mistakes are the last thing anyone should worry about. I have over the years in pushing for the simple architecture movement,, heard the concepts of error correction, error avoidance and the newest design for failure. Design for failure fits the simple architecture movement. Knowing that a system will fail design for that. Build in the recovery options for the system as you design it.

I argued many years ago with my paper Difference Architectures that the basis of good documentation was a minimalist approach. Finding the least possible number of pages to be published rather than the most. I came to that conclusion as I read the publication of a team members at a customer. The person documented everything. Every action that had to be accomplished for a task. While it was nice, and made for a solid server book, it was not a solid architecture. The difference architecture paper came out of that. Don’t document the standard, document the variance. So given a standard or reference architecture from a supplier, denote how your solution varies from that suppliers best practices. The difference architecture was the first concept I published into he simple architecture movement. It remains one of the most important components today.

The reality of consulting however is that you want to produce known value. See what I wrought. Consultants become Ozymandias in creating great works that end up never being read or seen. Just an empty desert into he IT directors office. Line after line of binders each containing the greatest architecture that has never been read.

How many pieces of a system require documentation? Do you document inputs (of course) if the inputs are different than expected. For example a video surveillance system has inputs, video cameras. Do you document the system? Yes and no, you should document the location of the cameras and then use the reference architecture for that system to denote how the video moves to the various security stations. Why recreate the wheel.? The same is true for any software architecture. Why do we document so much?

I worry that because consultants are expected to produce massive documents we limit the ability of solution architects. They are bound to creating massive documents that effectively limit the simplicity of a solution.

Complexity is the enemy of upgrades. It is also the enemy of continued operations. Simple allows for the organization to respond to change over time. It is easier to update the simple document than it is to update the complex and massive document. If I have to fix four pages, I won’t miss something. If I have to fix 400 pages I am likely to miss one, two or well 100 changes in that massive creation. Simple allows for change. Design for failure reacts to the ever changing software environment around us. Combining them? Priceless. Let us no more worship at the altar of complex architecture documents.