Eleven Rules of Design Documentation

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

• Forget school. Your writing isn’t going to be marked by an English teacher.
• It’s a statement of fact.
• stick to the facts, just the facts, and forget style.
• don’t use fancy words unless they are technical.

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 desk for longer than a any paragraph or document.
• Use diagrams.

Rule 6 A good table replaces even more paragraphs.

• for moments when all else fails, and you 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.

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
• 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.
• 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.