On a blog post titled “what good looks like,” Alan Inglis detailed a list of “project architectectural artifacts” that he wishes that previous architects would leave behind when a project is completed.
In his list, Alan details 10 artifacts (actually 14, if you use the ZF to catalog them) that he’d suggest should be created. His advice is interesting, but there is a flaw in the logic. I’ll examine his suggestion from a couple of viewpoints, to illustrate why I believe that his advice is incomplete, and to offer a suggestion for completing it.
It is normal, when we begin a project, to detail out the things that we wish we had. Therefore, we “should” create them for the next person. Viewpoint 1: at the beginning, looking forward, defining project requirements.
It is also typical to open up a maintenance project and need to make changes, only to find yourself wondering about the choices made by the person before you. Viewpoint 2: in the middle, looking back, trying to understand. (In my past dev teams, we called this process an “archeology expedition.”)
The problem with his list of artifacts (which is quite comprehensive) is that “wishing” does not constitute a requirement. If I create an artifact “for the future” that does not mean that the people, in viewpoint 2, will use it.
Unless there is a built-in development process that REQUIRES architects and developers to visit a repository, and withdraw relevant documents, then you have no business justification for performing the task.
I question every requirement that has no business justification, especially if it is not tied to a business process. This is easily fixed: tie the documentation ‘requirement’ to a business process… the process of designing architecture.
People in “viewpoint 2” should have the requirement of looking things up, in a specific place, for a specific reason. We need to carefully describe the processes around this “learning” phase. Why would we look things up? What things would we look up, and most importantly, what are the triggers or scenarios in which a lookup process is required?
Let’s draw the requirements for documentation from that development process… not from a wish list.
For example: If I believe that it will be useful to create a list of terms (glossary), let’s understand the scenarios where a list of terms would be useful.
I picked on the glossary, but EVERY ONE of the artifacts that Alan lists would have this problem. Each describes some tiny part of a much larger ecosystem of information. The moment the project goes into production, the artifacts must take their place among the hundreds of other relevant documents, from every other project. They need to be findable, consistent, and AUTOMATICALLY linked together in a way that minimizes the “archeology expedition” that “viewpoint 2” implies.
This is no longer a “project” problem. This is an enterprise problem. The data describes part of the architecture of the enterprise, and as such, needs to be maintained at the enterprise level, for the sake of engineering.
As Leo de Sousa pointed out in his reply to the Alan’s post, a repository is required. But it won’t be a simple one, where we drop documents. No, it will be a complex thing, that understands what each architectural element is, and how to find it, and how to link it to other elements, so that the artifact of the present doesn’t become the archeology of the future.
Nick, as the British say "You are bang on!". I will blog post on this in the next couple of days. I think my post on "How deep do you go" ... http://leodesousa.ca/2009/04/how-deep-do-you-go/ has some bearing on your post.
Software Development Tools TestDriven.Net 2.22: Support for Visual Studio 2010 Beta 1 Typemock Isolator 5.3.1 is Out! NDepend: Product Review Free Web Hosting to try ASP.NET 4 Beta1, VS2010 Beta 1, and MS Web Deployment Tool RC1 Microsoft Web Platform
Daily tech links for .net and related technologies - June 6, 2009 Web Development TDD, DI, and SoC with