Don’t Get Distracted by the Document

This may seem like an odd blog coming from a company that is so deliverable focused, but it isn’t. A design document is not just a document, but a powerful tool for figuring out an architecture. However, it is easy to get caught up in the “task” of completing the design document and lose focus on deeply understanding the architecture.

While we are staunch believers in the power of appropriate documents as tools, the document is not really the goal. It is the journey to produce the document that is important and the destination is not a complete document, but a complete understanding. It is critical that throughout the journey the architect’s focus be on the design, not on the document.

As you already know, if you follow our blog, we are meticulous about correctly scoping and formatting design information for maximum clarity. We follow our tried and true methodology, Investigative Architecture, which includes specific deliverables at its core. However, our documents are tools to achieve a goal; that goal is an appropriate and clearly communicated design. Much like a photo journalist uses photos to tell stories, we use well scoped artifacts to tell the story of an architecture.

When setting concrete deliverables as milestones, which we firmly advocate, it is easy to get caught up in completing the document as the primary objective. Always be mindful that a milestone is is not a primary objective.

Here are some tips for staying design focused:

1. Don’t transcribe! If you don’t understand exactly what something in the document means, keeping thinking, researching, or asking.
2. Maintain a list of questions. Answers to these are what stand between you and a complete understanding of the design.
3. Use the document when you tell the story of the architecture. Use the document as a whiteboard to explain your designs to your stakeholders. They will ask questions, which either you can or cannot answer…
   1. If you can, kudos!
   2. If you know the answer to the question, but it isn’t clear from the document, perhaps you need to refine the document to be more clear.
   3. If you don’t know the answer, add it to the questions list!

Check out some of our other articles on artifacts or, for some diagramming tips, read some of our other articles on diagramming. If you liked this, you might also enjoy It’s Not About the Tool or our anti-pattern article on How to Flub Your Design Review. We also have posted numerous presentations on our Investigative Architecture process on our publications page. Please contact us, if you want to learn more.

Comments