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 english creative writing project
- Forget school. Your writing isn 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 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.
- 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 the series
- Low Level Design - Think about the next step
- A Better Technique for Blogging and Writing - Markdown
- EtherealMinds Eleven Rules of Design Documentation (This post)