RE: Another dilemma for TWs - writing requirements

Subject: RE: Another dilemma for TWs - writing requirements
From: Rose -dot- Wilcox -at- pinnaclewest -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 15 Apr 2003 17:58:43 -0700


I was switched to doing Requirements (about 75 to 99% of my time) in January this year.

I will second the Sticky Minds website recommend by Diane.

The two books I found most helpful were Mastering the Software Requirements Process by Suzanne Roberts and James Robertson (Addison-Wesley) and Software Requirements by Karl E. Wiegers (Microsoft).

The technical writing skills I used for the job include the ability to understand complex subjects from more than one point of view. The audience analysis for Requirements spans a quite a range, from executives to developers to QA to users.

However, Requirements have a focused purpose, and that purpose is quite different from many documents I have written. The purpose is to drive and document an agreement by the various involved groups as to the programming solution to the business's needs. So understanding many points of view and communicating across those biases requires some writing finesse.

Also in our organization, the developers cannot design until the Requirements are signed off. Therefore, I have fast-paced deadlines. I use my organizational, project planning, and communication skills a great deal.

The writing is the same process as any other document... identify audience and purpose, outline, identify the business people and SMEs, and start filling in the gaps.

I don't know if you will be writing more of the Requirements than just the first ones. If there are no templates available, you would have to create them. However, since SDLC is following elsewhere in your environment you may have access to pre-created templates. Easy squeezy! Your outline is done for you.

Sounds like you might be at the "filling in the gaps" part already. The best approach for documenting requirements might be in a meeting with developers and the business people. In your case, one of each... that will make it simpler. You might have to run the meeting to ensure that the proper topics for your outline are covered or at least speak out! If you begin writing and something was left out during the meeting, you will have to decide if an individual can answer your questions or you might need to call another meeting.

Reviews also an spark second or third meetings, if a reviewer changes too much of agreed upon scope or if reviewers differ in their interpretations of what happened at the meetings.

The documentation will be invaluable for the users/developers to really understand each other. Both sides tend to resist the process. User are usually busy doing their actual jobs and don't see the benefit of giving of their time for the project. Management buyin makes a big difference, and eventually users start seeing the benefits as the software is developed and tested to meet their requirements.

The personalities and intents of various developers affect the process also. Some developers like to leave user requirements more open-ended so they have room for creative interpretation; others like to nail down every detail in the requirements so that they are protected against scope creep or last minute design requests by the users. Going to either extreme can be a problem, so try to strike a happy medium if you can.

If management is involved, sometimes they are very busy and throw a cog in the wheel by late reviews that question everything. It is very important to know who is the bottom line so he or she can determine whether or not to accept such last minute changes. *Save your review comments* in case your process is questioned later.

Clarity and timeliness are both very important. This produces a tension... do I chose to take shortcuts in my editing of drafts just to get the document out on time or do I hold it for a half a day so I can read it fresh in the a.m.? Sometimes I have been forced by management to send out a draft in a few hours with no self-editing time whatsoever. Ouch!

If management signs off on the Requirements as well as users and developers, you can be living in a fish bowl. Your attitude, writing skills, and timeliness will be very, very visible. If you are good at your job, this scrutiny can be a good thing. It has turned out well for me, but because the Requirements are very much a team document, I have had to let go even more of my highly battered tech writer vet ego (still intact after all these years (19!) of writing)... it has not occurred without pain... but it has been very beneficial for me.

To me, learning about the business (I work in a power trading environment, fast paced and complicated) is as fun as learning about complex technical subjects. I also enjoy the fast pace. Plus, it keeps me employed... :-)... can't beat that wit' a stick!

Good luck and have fun.

Rose A. Wilcox
CHQ, 17th Floor
Tranz1 QA/Documentation
Rose -dot- Wilcox -at- PinnacleWest -dot- com

It is not necessary to change. Survival is not mandatory.
--W. Edward Deming, Statistician

Purchase RoboHelp X3 in April and receive a $100 mail-in
rebate, plus FREE RoboScreenCapture and WebHelp Merge Module.
Order here:

Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at
Happy birthday to you, happy birthday to you, happy birthday TECHWR-L....

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: RE: Tech writer = office manager?
Next by Author: RE: Blame vs. Responsibility
Previous by Thread: Re: Another dilemma for TWs - writing requirements
Next by Thread: Re: Certification (was: Re: Hostility Towards Whatever)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads