Writing Technical Requirements: The Second Commandment

Scot Witt, Tuesday, July 17, 2007 @ 10:00 am

In our first installment, we found out it's important to know your audience and help your audience by using some common sense rules. Today, Knowledge is King. The second Technical Requirements Writing Commandment is:

II. Know of Which Yea Speak, Lest Your
Reader Will Know Yea for a Fool.

This is the second rule of writing. If you do not
completely understand the subject matter, your reader will know you don;t know it within a sentence or two. Here's how to avoid this trap:

•   Find SMEs (Subject Matter Experts) both for the System and the Business

       -Recognize and ask the questions you need to ask so you understand.
       -Make a VISIO diagram- shows gumption and you have something physical to change
       -Do the research- the internet and existing documentation can help frame and provide background

• · Never ever feel your questions are stupid- if
  you have a question, it cannot possibly be stupid.

       -Well, if you're a consultant it might sound stupid to the customer.
               * Phrase it to get their buy in- "Help me out here...<insert Question>"
               * Look like you're struggling- "I'm having a lot of trouble with <insert Question>
               * If you don't understand the answer, rephrase it,
re-address the issue by relating it to                     something you already know

• Use the Web. Google is a wonderful and greatly
  used tool for Business Analysts and technical writers. You can use it, too.

Consider what process you're starting with your requirements:

1. Gather- interviews, document reviews, project documents, research
2. Organize- outline, lists, numbering systems
3. Write- get it on paper or the wiki
4. Review- get revisions from SMEs and Team Members
5. Publish- In waterfall environment, this is the sign-off, in agile it's start of the feature
6. Revise- changes-

Now think about what your reader brings to the table:

• At least one goal
• Years of experience
• Years of education

Anyone can hide behind long words, buzzwords, jargon and some irrelevant graphics. But the folks who need the material you're providing have extremely limited time and patience.

If you can't explain your topic in simple, easy to digest words, you don't understand it.

Next Up: Use Cases

Related posts:

1. Writing Technical Requirements: The Third Commandment
2. Writing Technical Requirements: The First Commandment
3. Writing Technical Requirements: The Fifth Commandment
4. The Ten Commandments for Technical Requirements: VII: Presentation: The Art of Gladness
5. The Ten Commandments for Technical Requirements: VI. Santa is Not The Only Clause

Comments (0)

Technologies and Platforms

Comments

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

None so far.

Leave a comment