Greg Ferro's Eleven Rules of Design Documentation

Here is Greg Ferro’s approach to designing network design documentation. The “world” of networks is too big and varied to have only one document to cover more than one or two projects, but here are some rules to write a detailed Design document.

Disclaimer: The original article was written by Greg Ferro and was published as EtherealMinds

 

Eleven Rules of Design Documentation. Unfortunately, web page https://etherealmind.com/rules-design-documentation-etherealmind/ is not available anymore, probably because of Greg’s retirement and … who knows.

 

About Greg Ferro

Greg was a Network Architect and Security Engineer / Designer / Freelancer working in the UK and has worked for resellers, Large Companies, and Service Providers on a wide variety of products and suppliers. He also co-organized the Packet Pusher’s Podcast on the network. He was a very active and interesting blogger to read. 

Greg’s LinkedIn Profile: https://www.linkedin.com/in/etherealmind/ 

Greg’s Tech Field Days Profile: https://techfieldday.com/people/greg-ferro/

Source of French translation published by Benoit: https://www.networklife.net/2011/03/11-regles-de-design-reseau/

I almost fully agree with Greg’s rules; therefore, I have published another copy of Greg’s rules to keep it on the internet.

The Greg's rules of design

 

Rule 1 — Design documentation is not a creative writing project.

• Forget about the school. Your English/French/Etc will not be scored by a teacher.
• It is a statement of facts.
• Be content with the facts, just the facts, forget the style.
• Do not use fancy words.

Rule 2 — A Design is not “Read”, it is “used”.
Presentation is less important than raw facts and data.
You should not read it as a book.
It will not be published.

Rule 3 — Do not write a paragraph when a chip would be enough.

• When you write a paragraph, you waste time. Use fleas.
• A chip makes you focus on the data, instead of thinking about grammar.
• To be brief, induces less error of understanding.
• You spend less time writing.

Rule 4 — A chip must always be used in place of the paragraphs.

• Look at the rule before.
• The only exception is the introduction, where you introduce the context of the project.

Rule 5 — Use diagrams

• A diagram is more understandable than a chip, 90% of the time.
• It is possible to build an entire Design with ONLY diagrams.
• Schemas will be used more often and will stay on the tables longer than paragraphs in a document.
• Use diagrams. 

Rule 6 – A good table replaces even more paragraphs.

• Do you think you need a paragraph? Use a table.
• The tables contain as much information as a diagram.
• More convenient to talk about “why”. Left column = reason, right column = how, why, what.
• The invoices for the equipment.

Rule 7 — Not using adjectives is the job of pre-sales and managers.

• The only opinions to have are those regarding technology. 

Rule 8 — A design does not need more than 4 levels of development.

• Really, no more than 4.
• Make sure you understand why you need to present a document before you start.

Rule 9 — The Design process goes from least specific to the most specific.

• Thus, the business plan becomes a high-level design and a detailed design becomes an operational document.
• Each part contains more and more specific information, and fewer and fewer words.
• If what you write is no more explicit than the previous document, do not write it.

Rule 10 — Use the appendices for irrelevant information that you deem relevant.

• If you have any doubts about whether something is completely relevant, 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 websites
• Assume that the reader knows something about the subject. You don’t need to explain everything.
• You will need to explain some things, which is the purpose of the design.
• You are not paid per page.
• People will not be able to read a long document.
• You waste your time writing too much.
• No one will read it.
• Do not fall into the trap of big documents that are of better quality. They are not. 

That's all.

• Go and design something.
• Do the research and testing.
• Always document or lie before, during, and after.. Especially after.
• Be short, simple, and it will be cool.