Prose: Great for Novels, Lousy for Solution Design

While we often find ourselves advocating for design documentation, we typically are referring to “some” design documentation vs. “more” design documentation.  When it comes to design documentation, more is actually not better.  We have encountered customers, and even other consulting firms, that deliver design documentation by the inch – measuring design quality horizontally across the binding.  We recommend not doing this!

We strive for appropriately sized designs, with the right amount of structured information to clearly describe a design.  Most typically it is use of prose that expands the design documentation – page after page of unstructured text.  This prose does not make the design more clear, but has the opposite effect:

1. Turns the significant elements of the design to needles in a prose haystack.
2. Intimidates your audience by expanding the size of the document they must consume to understand the design.
3. Relies on the wordsmithing skills of each individual author, therefore reducing the likelihood of success and consistency of design documents across the organization.
4. Increases interpretation variability.  This may create an interesting dialogue in a literature class, but is not useful for technical designs.

We have found that the most effective way to right-size a design documentation is to ban prose, or at least employ it on an exception-only basis, and stick to structured constructs, like…

Diagrams!  This is, not surprisingly, our preferred method to articulate a design.  Check out some of our diagram articles for more on this topic.

When augmenting any diagrams with textual information, we always employ a structured format, with strong attention paid to using concise information in the structure. Our content hierarchy after diagrams is:

1. Tables
2. Lists
3. Tightly structured narrative, using short concise paragraphs with liberal use of headings and sub-headings
4. Unstructured narrative (very sparingly!)

Modifying the design templates for your organization to rely less on prose is an easy way to inject clarity and consistency into designs.  It makes design documents easier to produce, easier to read, and saves trees!  Contact us if you have any questions or would like some assistance streamlining your architecture practice.

Comments