I got an email from a reader who asked (more or less) about my approach to design documentation and how to prepare good documentation and whether I have any design templates that he could use.

Good question ! In my experience, networking is too wide and varied for a single document to cover more than one or, if you are lucky, two projects. But here are my Rules for writing a detailed design.

EtherealMind’s Rules of Writing Designs

Rule 1 – A Design Document is not an creative writing project

Forget school. Your writing is not going to be marked by your English teacher.

It’s a statement of fact. There is no reason for creative writing.

stick to the facts, just the facts, and forget style.

don’t use fancy words unless they are technical fancy words.

Rule 2 – A design doesn’t get “read” it gets “used”.

Therefore layout matters less than facts, data, details and raw information.

Formatting doesn’t matter. Really.

It shouldn’t read like a book.

It won’t be published.

Rule 3 – Never write a paragraph when a bullet point will do.

If you are writing in paragraphs, you are wasting time. Use bullet points.

A bullet point makes you focus on the data, instead of waffling about grammar.

Brevity means less mistakes because of bad interpretation.

You spend less time typing.

Rule 4 – A bullet point should always be used instead of paragraph.

see previous rule.

only exception is the introduction, where you put some business background to the project.

Rule 5 – Use Diagrams

a diagram is better than a bullet point ninety percent of the time.

it’s possible to produce an entire design in diagrams ONLY.

Diagrams will be used more often and stay on peoples’ desks for longer than any paragraph or document.

Use more diagrams. Get good at making diagrams quickly.

Rule 6 A good table replaces even more paragraphs.

for moments when all else fails, and you still think you need a paragraph ? Use a table.

tables carry almost information as a diagram.

most useful for “why”. Left Column = reason, Right Column = how, why, what.

and bills of materials.

Rule 7 – Never use adjectives, that’s what sales people and project managers are for.

any words that end in “-ly” should not be used.

the only opinion you are allowed to express is about technology.

Even then, I’m dubious.

weasel words are not allowed. Say what you mean.

Rule 8 – A Design never needs more than four levels of headings.

Really, any more than four means your document outline is faulty.

make sure you know how to use the outliner feature of your word processor.

make sure you understand why you need to outline a document before you start.

Rule 9 – The design process goes from least specific to most specific.

Thus the Business Plan becomes High Level Design becomes a Detailed Design becomes a Operational Document.

Each one contains more and more specific information, and less and less words.

No exceptions.

if what you write isn’t more explicit than the previous document, then don’t write it.

Rule 10 – Use appendixes for irrelevant information that you think is relevant.

If you have any doubt about whether something is completely relevant, then use an appendix.

better yet, use a reference to an external resource.

Rule 11 – A Big Document is a Failure

use references to external documents and web sites, don’t copy a website into a document.

assume that the reader knows something about the topic. You don’t need to explain everything.

You will need to explain some things, that’s the purpose of the design.

You don’t get paid per page. You get paid per document.

People won’t review a long document and then your errors / mistakes get missed.

you waste your own time editing it.

no one will read it.

don’t fall into the trap of big documents are better. They are not.

That’s it.

Go and Design Something.

Do your research and testing.

Always document before, during and after. Especially after.

make it short, simple and it will be sweet.

Other Posts in This Series