Friday, January 21, 2011

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.

No comments:

Post a Comment