Assumption-free architecture documentation

When reviewing architectures, I sometimes run into architecture description documents that contain long lists of assumptions. There are some negative connotations associated with assumptions. They often read as a “list of things other people should take care of.” They seem to imply that the author:

  • has not checked whether the assumptions are valid;
  • does not want any responsibility for the assumptions;
  • does not accept any blame if the assumptions do not hold;
  • avoids dealing with uncertainties.

It is better to avoid assumptions in architecture documentation: it is not coincidence that the RCDA Solution Definition template does not have a section called “assumptions”. There are several kinds of assumptions in architecture documentation, and they can usually be rephrased quite easily:

  • Scope limitation: “We assume that the client will take care of the network connection between the data centre and the Gouda office.” Rephrase: “The scope of the solution excludes network connectivity between DC and Gouda office.”
  • Interpretation: “We assume that a Spring/Hibernate framework on JBoss fits the client’s open source policy.” Rephrase: “Requirement RFP.OS1 Open Source is fulfilled by utilizing a Spring/Hibernate framework on JBoss. “
  • Dependency: “We assume that the PEAR application suite will run on a Websphere platform.” Rephrase: “There are no instances yet of PEAR application suite 4.5 running in production on a JBoss platform. Compatibility will be validated during the elaboration phase.”
  • Pending agreement: “We assume that the Testing Centre will  validate the performance criteria.” Rephrase: “The solution is based on cooperation with the Testing Centre for the validation of the performance criteria. Agreement about this cooperation is currently being negotiated by…., expected outcome October 15th at the latest.”
  • Pending decision: ”We assume that management will approve the necessary investment in the new Firewall “. Rephrase: “Management approval of the Firewall investment is expected November 10th. If it is not approved, the first three paragraphs of section 5.4 and figures 4, 5 and 6 of this document need to be revised.”

Care should be taken to place these rephrased assumptions in an appropriate section of the architecture documentation. Scope limitations and requirement interpretations belong in the Requirements section. Dependencies, pending agreements and decisions usually represent architectural concerns that have not yet been fully addressed, and belong in the Concern Register or equivalent section of the architecture document. Do not forget to document the implications of these. Many assumptions also lead to risks and may require mitigation measures, which should be added to the risk register and project plan.

Rephrasing assumptions this way has two clear benefits:

  • Clarifying what type of assumption we are making leads to more clarity what actions need to be taken to deal with them.
  • It avoids the negative “cover your behind” connotations many experience when reading assumptions, and gives a more pro-active impression of an architect who deals with, rather than avoids uncertainties.

What are your experiences with assumptions in architecture documentation? Are there more types of assumptions than the five categories listed above?

Leave a Reply

Your email address will not be published. Required fields are marked *