Writing Technical Requirements: The First Commandment

Scot Witt, Monday, July 16, 2007 @ 10:24 am

Business Analysts seem to come from two areas:

• Developers who want to be Writers
• Writers who want to be Developers

Coming from the second group myself, I've often been asked to help neophyte writers improve their skills. Trading writing tips for tech points is a good thing for me since I can abstract and write from today until tomorrow- but unless I understand what I'm writing about, it's more than obvious. Hence my 'quickie writer's course, the Ten Commandments to Writing Technical Requirements.

Here's the First Commandment:

I. Thou Shall Always
Address the Audience's Needs

You have three major audiences for and Requirements
Documentation:

• · Developers/IT Professionals
• · Business and Project Managers
• · Quality Assurance Staffers

Each audience has a different educational and experiential background and their own jargon.

To address each audience's needs, follow these guidelines:

1. Eliminate
jargon. You may know what SQL means,
but the VP of Order Management may not and you do not want to make that person feel inadequate nor do you really want to explain what SQL is- I usually say 'queries the database' and leave it at that.

2. Clearly
and effectively organize and label the elements of your document. We'll get into this very important area in a future blog, suffice it to say here you can get a big head start by:

       - Splitting your material into logical groups your reader can easily understand

       - Properly labeling each group so your reader can scan the doc to find what s/he wants.

       - Use an outline- revise the outline when needed, but use it.

3. Use
consistent terms and phrases throughout the document. Don't call it 'The Application' in one are and 'The System' in another. pick one and stick with it.

4. Eliminate
buzzwords. Don't use 'initiate' when you mean 'start.' Don't use 'terminate' when you mean 'end.' And, one of my pet peeves- 'entitle' is not a fancy word for 'title.' If you are entitled to something- it means you deserve or earned it.

5. Avoid
clauses. If you need to use one, put it at the beginning, but not in the middle since the reader can't parse it that well, or end of a sentence, if you use one clause in a sentence you can put it at the end, but that should be your second choice. See what I mean?

6. Avoid
passive voice- see Commandment V. For now, just remember "Boy paints the fence" is ACTIVE voice and "The fence was painted by the boy" is PASSIVE. Note both sentences  mean exactly the same thing. It has nothing to do with verb tense, it has to do with who's doing what in the sentence.

7. When
using the command form, use "must," not "shall."
"Shall" is regal and antiquated. Better yet- ignore all those 'The System must....' statements entirely and just start writing after the word 'must.'

Writing is organized thought. If you can design it, you can
write it. Write it as though you were explaining it in a conversation with your
non-technical parent. Except my mother. Ain't no way that'll happen. In such a case, you do not talk down to them,
but try to make them understand. 

This is the first rule of any writing.

Next Up: Knowledge.

Related posts:

1. Writing Technical Requirements: The Second Commandment
2. Writing Technical Requirements: The Third Commandment
3. Writing Technical Requirements: The Fifth Commandment
4. The Ten Commandments for Technical Requirements: VI. Santa is Not The Only Clause
5. Commandment IV: Keep Business Rules Simple Unto All The Rules of Your Life

Comments (2)

Technologies and Platforms

Comments: 2 so far

• Leave a comment
• Comment feed for this post
• TrackBack URL

1. 

   you have two times “avoid” point

   Comment by tradeready, Tuesday, May 5, 2009 @ 6:27 am

2. 

   8. Use
   good titles

   Comment by Stepan, Friday, September 18, 2009 @ 7:34 am

Leave a comment