Why “good” doesn’t happen

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.

Context

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.

Suggestion

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. 

• Would it be on THIS application, or any application tied to the same business unit? 
• What do I need to know about a term? 
• If I look up a term, would it be natural to link that term to the conceptual data model (if applicable)? 
• What about changes in the meaning or use of the term over time? 
• If a term has changed, or an older term is no longer used, what guidelines must be followed to update that glossary? 
• Should we keep older definitions, so that people inspecting older code can understand the code? 
• Should we leave advice to those poor souls for how to interpret an older term in the context of a newer practice or process? 
• Assuming many projects would use the same glossary, should we tie each term to the project or app that needed it?  (That way, a term won’t be deleted if a system that needs it is still running in production).

Discussion

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.