AIM Your Audience

Quality of design documents is the perpetual issue which I had to face on every implementation I had ever had a chance to work on.

On my very first Oracle eBusiness Suite implementation project my manager asked me to paste everything, including source code at 6pt, into one big Word document to make sure nobody reads it. I am very thankful to my manager because I learned how not to write design documents and I read AIM Guidelines, both volumes. Question to the audience: who has ever seen these documents?

As I was advancing my skill of application design, I got more responsible for the quality of the documents which my team was delivering to the customer. I found that understanding the audience for the document was one of the key concepts which improved the quality of the deliverables. Let us look at the audience for the key design documents in AIM methodology.

Functional Design (MD050) is written by a functional consultant for the customer’s subject matter expert and for the technical lead. Identifying the audience for this document is the simplest. It is clearly understood on most of the projects

Identifying audience for technical Design (MD070) is not that obvious. The technical design is written by the technical lead for the developer and for the functional consultant. Functional consultant should validate that the desired functionality will be delivered as envisioned, developer should validate that the technical solution is clearly explained.

Installation instructions (MD120) is the most abused document, especially on smaller implementation. The instructions are written by the developer for the migration team and for the technical lead. Migration team needs to validate that the instructions are clear for execution. Technical lead needs to record the list of files and other objects for reporting, interdependencies etc.

Where is the source for quality? It is in variety of the audience. Let us look at MD050. Functional consultant writes this document for the customer’s subject matter expert. SME is sure to stand guard to receive the clearest document possible. This is the reason why MD050s are typically of high quality. The exception of the rule is when you are implementing a brand new product where neither SME nor functional consultant understand what to do. MD070 is written by the technical lead for the developer. This document is most abused on most of the implementations I ever participated.

Predominantly, it comes from the fact that the person who writes the technical design is the one who’ll be coding it. Such setup produces the worst technical design which later translates in a very bad code. We found that the best technical designs are produced in the situation when one consulting company provides technical leads and another consulting company provides developers. With such layout developers would stand guard to ensure that the technical design is of the best quality. Similarly, MD120s are reaching the top of their quality when code migration is performed by a team of consultants not associated with the build.

Summary: the key to the quality of design documents is in setting up the audience to have ‘natural’ guardians whose success depends on the quality of the documents they receive.