Re: "Allow" vs. "Require"

Subject: Re: "Allow" vs. "Require"
From: Keith Hood <klhra -at- yahoo -dot- com>
To: Lauren <lauren -at- writeco -dot- net>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 10 Apr 2012 12:28:44 -0700 (PDT)

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.

http://bit.ly/doc-to-help

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as klhra -at- yahoo -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

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.

http://bit.ly/doc-to-help

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

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


References:
"Allow" vs. "Require": From: Dan Goldstein
Re: "Allow" vs. "Require": From: Keith Hood
Re: "Allow" vs. "Require": From: Lauren

Previous by Author: Re: "Allow" vs. "Require"
Next by Author: Re: Title case in documentation
Previous by Thread: Re: "Allow" vs. "Require"
Next by Thread: RE: "Allow" vs. "Require"


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


Sponsored Ads