EtherealMinds Eleven Rules of Design Documentation

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 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’ desks for longer than 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. 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 A Series On The Same Topic

  1. Low Level Design - Think about the next step (18th March 2011)
  2. A Better Technique for Blogging and Writing - Markdown (15th December 2010)
  3. EtherealMinds Eleven Rules of Design Documentation (16th November 2010)
About Greg Ferro

Greg Ferro is a Network Engineer/Architect, mostly focussed on Data Centre, Security Infrastructure, and recently Virtualization. He has over 20 years in IT, in wide range of employers working as a freelance consultant including Finance, Service Providers and Online Companies. He is CCIE#6920 and has a few ideas about the world, but not enough to really count.

He is a host on the Packet Pushers Podcast, blogger at EtherealMind.com and on Twitter @etherealmind and Google Plus

You can contact Greg via the site contact page.

  • http://www.larsenconsulting.net Robert Larsen

    Thanks Greg — in an ideal world, I would wholeheartedly agree with you. Unfortunately, we live in the real world, and so I would like to propose the following:

    Rule 12 – The Customer Pays the Bills
    - any of the previously defined rules can be overridden at the customer’s request.
    - if the customer wants wordy design documents, the customer shall get wordy design documents.
    - if the customer wants information to be repeated in design documents, then information shall be repeated in design documents.
    - if the customer wants excessively lengthy design documents, the customer shall get excessively lengthy design documents.
    - if the customer wants low-level detail in high-level architecture documents (despite such detail being already present in HLD and/or DLD documents), the customer shall get low-level detail in high-level architecture documents
    - etc. etc.

    I’m currently trying to close off a Solution Architecture Document (comfortingly called a SAD) for a major incumbent, and all of the above exceptions (and more) are applicable. The document currently stands at 330+ page, and I know for certain that once it’s signed off, nobody will ever read it again.

    Rob.

    • http://etherealmind.com Greg Ferro

      You are seeing the symptom but not the cause. This means that the customer doesn’t know the Rules, therefore expects to receive a “textbook”. You must teach the customer to expect a proper design and not a high school assignment. It’s probably too late for this project, but you’ll know for the next one.

      • http://www.larsenconsulting.net Robert Larsen

        Teaching the customer is a nice idea, which can work with some of them — but be prepared for the ones that don’t want to be taught (for any number of reasons). This is generally a problem in larger organisations (such as multi-national ISPs and incumbent telcos), and I’ve seen it on more than one occasion while working in EMEA, as well as in my current project here in APAC. Of course, I will always try to educate the customer, but in these cases you’ll likely be fighting a losing battle no matter how much logic and common sense you apply. Being able to adapt in these kind of situations comes with experience and is all part of the job.

  • http://aconaway.com Aaron Conaway

    Rule 11 is the Truth handed down from the Gods. Before my time with my current company, a consultant was paid to implement an unnamed project. The result was a 600-page document explain the implementation and setup. Guess how many people read it? Exactly the number of people you think would read it.

    • http://etherealmind.com Greg Ferro

      One look and you would fall asleep.

  • http://blog.paulleroux.net paul

    this plays nicely with an article I am drafting about Physical network management. I was going to make a few point about Docs and diagrams, I will just point to your article.

  • Josh Barron

    Any possibilities we could get an example of a design document based generally upon the rules outlined above?
    I’m moving into more and more network design and engineering and less and less into server administration. I’d like to possibly chew on some examples if you could provide them.

    • http://etherealmind.com Greg Ferro

      I’ve got some plans to write a book on the topic, hopefully in the new year.

  • PR Steels

    How about organizations that follow ITIl? How do you write a Service Design Package (SDP) using the 11 rules you mentioned above?

  • loopback0

    Great post, Greg. I have found that even a basic Visio layout with a few labels keeps everyone from drawing it over and over and over again on a white board. Change Management LOVEs them.

  • Serge

    I’m one of the few people at my company who writes design documents. The main audience for my design docs: me! I find the exercise of writing a design doc helps produce a better design. I think alot when I write. Is what I’m saying true? Will this actually work the way I think it does (translates to test cases)? Is there a better way? What about certain corner cases? Etc… I also find it useful as a reference. When I get asked a year down the line why I did things a certain way, the answer is usually in my own design. -Serge

  • Pingback: Total Network Managment: Some things to consider

  • Pingback: A new way of blogging – Markdown ñ My Etherealmind

  • http://formalgut.de Thomas

    I really like your approach, but sorry, linguist reflex / shudder:

    Rule 7: I guess I know what you mean.
    But: “words that end in ì-lyî should not be used.”
    I take it to refer to _adverbs_ derived from adjectives, such as ‘quickly’, and adjectives such as hourly. (supply ends in the letters ly, too…)

    Anyway, formulated like that, it sounds like an ironic imitation of self-proclaimed “style/language experts”. (check e.g. languagelog for detailed by experts on English grammar)
    It’s plain wrong both for adjectives and adverbs as word classes – it’s deadly right for many semantic classes.

    To start with, what about ‘only’?
    In any case, it’s plain wrong if applied literally: ‘left’ and ‘right’ are adjectives, too. ‘Next’ is either an adjective or adverb, and so on.

    • http://formalgut.de Thomas

      Sorry for the less than optimally structured rant.
      But from a linguistic perspective, rule 7 is the equivalent of saying ‘don’t cross the street, when something’s red on the other side.’

  • Pingback: Low Level Design – Think about the next step

  • http://www.networklife.net Ben

    Hi Greg,
    Can I quote you and translate this article in french for my blog ?
    By the way, Thank you for this awesome blog ;)
    Regards,

  • Pingback: 11 rËgles de design rÈseau | NetworkLife

  • Pingback: Some Tips on Writing Design Document « I, Geek

  • Dhana Kaneshayogan

    Can you make this into a poster and sell it please? I’d like a copy and a few more to pass on to some others.

  • Abs

    I like it, Thank you very much for sharing.

  • Petter

    Hi, Thanks for your useful information. it would be great if you could attached a sample doc for better understanding

    Regards

  • Pingback: Screencast: Knowledge Management in Technology – Part 1 — EtherealMind

  • Pingback: Screencast: Knowledge Management in Technology – Part 2 — EtherealMind

  • Pingback: Screencast: Knowledge Management in Technology – Part 3 — EtherealMind

  • http://www.nish.com/ Nish Vamadevan

    excellent write-up Greg!

    • http://etherealmind.com Etherealmind

      Thankyou.

Subscribe For Weekly Updates by Email

Get a Weekly Summary of Latest Articles and Posts to your Email Inbox Every Sunday

Thanks for signing up. Look for the email from MailChimp & make sure you confirm your email address. You may need to check your spam or gmail settings to be sure of receiving the email.

Note: You can unsubscribe at any time using the link at the bottom of every email.