TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Lauren, we just have a difference in opinion on how requirements are written and used. It's pretty simple in my way of thinking: a requirement is a statement of something that must be included in the software, some functionality or feature. A specification is a *refinement* of a requirement, something that provides more-exact details of how the requirement should be implemented. For example, there may be a requirement that the software provide a dialog box that is used to change the font on the screen. A specification sets whether or not the box is modal.
All the developers I've ever worked with always preferred the requirements to be as loose as possible. They wanted to use their own ideas of exactly how to implement the pekele schlepping function. They would say they don't need to be told how to make the pekele do the schlepping; they already know how to write that code. What they need is to be told whether or not to build it in, and that basically is really all a requirement does. Some want to stop at that level of detail. The better a programmer thinks he is, the more likely he is to want more slop. I agree that too much looseness produces bad software and inefficient projects. But there's no way a technical writer is going to force precision on an unwilling programmer unless he has the boss in a holster strapped to his waist, and maybe not even then. Some places the developers want to go directly from the brainstorming meetings into banging out lines of code, and they wouldn't read
requirements if you kidnapped their pet gerbils.
In my book, a use case or a user story is what shows how a user actually interacts with the software. Requirements can be developed from a use case and vice versa. Some shops want use cases and care nothing for requirements, some shops are the other way.
As to when specs are written, that depends. Sometimes I've knocked out all the requirements in one lump, then backfilled with specs later. Sometimes, my preference, the specs for each requirement are included in a section in that requirements doc. It depends a lot on the type of development model used in that shop.
There's no right or wrong way to structure requirements, use cases, specifications, or any other document related to software. There's only ways that serve that particular shop's needs adequately and those that don't.
I prefer uranium. It makes a very pretty red pottery glaze.
________________________________
From: Lauren <lauren -at- writeco -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Sent: Tuesday, April 10, 2012 12:52 AM
Subject: Re: "Allow" vs. "Require"
On 4/9/2012 6:13 PM, Keith Hood wrote:
> These are requirements you're working with. A requirement is just that - something that is required. It's something that the software must do. So the requirement should be written as an imperative - the software will or the software must.
These, however, are not generic requirements, they are design requirements. Such requirements are not just about what the
"software must do," they are about how the user will use the software.
> For the purpose statement of the requirement, just put "The RCP will provide the user a mechanism for schlepping the pekele."
I have done some development in my time, but I do not understand what a developer is supposed to develop with that requirement. If I read it, I would wonder, is the tool already developed and I need to develop around it or am I to develop that tool that "will provide" the mechanism and I will wonder what is the nature of the mechanism.
I think that design requirements should be specific and not lead developers to guess what is they are supposed to develop. Developers should focus on functionality and not have to worry about design.
> That says what functionality has to be built in but allows a lot of slop in deciding exactly how to implement it, just the way programmers want it.
"Slop" in requirements is bad, precision is necessary. Ineffective programmers may want latitude in design requirements, but that is not because they will produce useful programs.
> When you write the specs for that requirement, there's where you can put in nitpicking about whether the pekele schlepping dialog box is modal, whether or not it has a cancel button, etc.
What do you mean "when"? I read this question as being about how to phrase a design requirement. How can the specifications become *more* concise than the design requirements? They can have less detail than design requirements, but they should not add anything to them, like how the user is to interface with the application. Specifications are built around requirements, but they should not change or drive them.
> What the frabjapping bleep is a pekele?
A pekele is a four-stringed guitar-type instrument made with potassium instead of uranium.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.
Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.
Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.
