Blog | Write what you mean

I enjoy documenting. I enjoy the design thinking that goes into good detailing, the artfulness of laying out a page, the methodical assembly of a rigorous documentation set. As the years have passed, I have codified a list of ten rules for exceptional documentation. Some have been bestowed upon me by peers like perfect golden nuggets of wisdom, others have come to me in epiphanic dreams, and yet others I have had to learn the hard way with gritted teeth and much yelling.

I hereby release this list into the wilds of the internet so that future architecture students may stumble upon its wholesome goodness in their moments of need.

An archive of the list can be accessed here.

6. Write what you mean

Imagine…

Preparing to print your documentation set.

You spend hours chasing cross referencing and documentation tags down their respective rabbit-holes. You make sure your plans point to your sections, which point to your details, which point to your schedules. And you check that each tag is an accurate signpost, an essential marker to help the builder navigate your drawings. Then you spend more hours adding titles to details and finishing touches to annotations. Like a Shakespearean playwright, you craft exquisite notes of great clarity, each one an extra push when lines and hatches don’t quite suffice.

It is tempting to number each cross reference, documentation tag and detail according to industry standard protocols and leave it at that:

• Elevations are north, south, east and west
• Windows start from W01
• Details start from Detail 01

This is a solid start, simple identifications for core referencing. But an exceptional documentation set goes further, it takes every opportunity to aid comprehension. In this, the English language is your friend:

• Material codes should infer their materials. If you can guess which materials BR-1, CO-1, GL-1, TI-1 and TM-1 are likely to infer, then it’s a good chance your builder can too.
• Detail numbers might be simple, but their names should tell a story. They are elevator pitches that explain at a glance the information each detail contains. Instead of section detail, try box gutter detail, window sill detail or skirting detail.

The English language is pretty handy for the longhand of annotations too. To comply with Rules #01, #02 and #04, the best annotation is the one you don’t use. But when you absolutely must, they should:

• Use as few words as possible
• Be strictly written in the imperative
• Say what they mean

So instead of:

• Builder is to install 3mm mild steel 30mm diameter tubular handrail spot welded to steel balustrade as required with Ferrodor paint finish, refer to specification for details.

Try:

• Install 3x30mm diameter handrail (ST-1) welded to balustrade at 200mm centres. Paint finish (PA-1).

From 27 words to 14, with two inflexible materials swapped for flexible material codes, and the laziest phrase (as required) and most tautologist phrase (refer to specification) eliminated unceremoniously from existence.