Colin’s IT, Security and Working Life blog

May 18, 2009

Maybe the “perfect security theoretical paradigm” needs work

Filed under: Documentation — chaplic @ 1:03 pm

 

There’s a lot of a talent in the IT and Security industry. However, I tend to find the quality of documentation, bid responses and proposals to be massively variable. OK, that’s being charitable, it’s usually pants!

Here’s my thoughts on successful technical document writing, based on peer reviewing documents and also evaluating tenders

Boilerplate text, content copied off the vendors website and splattered in documents is utterly evil, frustrating and waste of time. Your readers have probably read it already and the language and terminology used won’t be consistent with your document. It sends a message that you are lazy. If you must, edit it appropriately or include it in an appendix.

By the same token, please, please, please don’t write business bullshit – you’ve read it, you know what it is – AVOID!

If you are responding to requirements, include a table in your document which, column-by-column  states the original requirement, then how you have satisfied this (usually just a reference to a section of your document. This serves two purposes – it demonstrates to the reader that you’ve been thorough and also gives you a tool to spot if you have missed anything.

Just like at school, tell me your working and read the question.

I’ve recently just reviewed a number of vendors proposals and lost count of the amount of responses to the requirements that have been answered  what they would like the answer to be (frequently missing responding to some requirements completely).

Also, Don’t just present a solution as a fait accompli. Remember, anyone reading your document may have at least as much technical skill as you, so will have an understanding of different options. Explain to them the reasons why you have gone down the route you have. For every point you make, make sure you defend it.

You should be an absolute guru at Visio! The adage about a picture is absolutely true, it helps break up text and can also explain your thinking to audience members who think visually. Consider a big “everything in” Visio at the start of your document, then take sections of that graphic when you are expanding the solution later.

Most vendors will have Visio stencils available – use them. No matter what kind of document you are writing, presentation is an important facet of getting your message across.

To keep document sizes manageable, I save my visios as .GIFs and import them into word. And whilst we’re on the subject of document size, don’t include large spec lists, code,  or other generic lists of information. Include them in an appendix.

Overall, it doesn’t matter how your technical solution is, it can live or die (or not even be born) depending on how good your documents are – hopefully this will help improve them!

 

Advertisements

Leave a Comment »

No comments yet.

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Create a free website or blog at WordPress.com.

%d bloggers like this: