Don’t Get Distracted by the Document

October 16, 2012 | , ,

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.

Dan Hughes
Dan Hughes is a principal consultant and partner at Systems Flow, Inc., where he leads the technology services practice. He has 20 years of software engineering experience spanning a broad range of technologies and techniques. Startup to enterprise, he has launched, managed, and executed all aspects of both product and enterprise life cycle, delivering complex, enterprise-scale architectures for clients in the public and private sector, in industries ranging from banking and insurance to international development. Dan holds a Bachelor of Science in Computer and Systems Engineering from Rensselaer Polytechnic Institute. For more details, please visit Dan's LinkedIn profile
Dan Hughes

Latest posts by Dan Hughes (see all)


Comments are closed.