Re: Kovitz vs. traditional
Kovitz (in Practical Software Requirements) states that the
functional specification is the 'what' and the design
specification is the 'how'. I believe that, traditionally, with
step-by-step development, the design spec was the 'what' and the
functional spec was the 'how'.
Although I'm inclined to go Kovitz' way, I'm wondering how you
have declared the 'what' and the 'how' in your endeavors to
provide useful documentation.
Just to clarify, the only reason the book mentions "what" and
"how" is to point out what a vague, useless way of making
distinctions it is. (And also to familiarize readers with the
commonly accepted definitions.) I'm in agreement with Geoff Hart
that it's purely academic, or maybe not even that.
No two people distinguish "what" and "how" the same way. That's
no surprise, because everything is "what" and everything is
"how". The screens are "what" the software displays as well as
"how" the users enter and view data. Entering and viewing data
is "what" the users do, and "how" they get information for some
real-world job like picking items off shelves for shipping.
Sending signals to a motor is "what" the software in a
computer-controlled lathe does, and "how" it makes the lathe
shape pieces of wood.
This is not a helpful distinction--one where everything you're
considering meets the criteria for both sides of the distinction.
I've seen people get into useless semantic arguments about which
decisions are "what" and which are "how", and thus which belong
in which document, which belong in which phase of the development
process, etc. I'd like to steer people away from that.
Better to address the actual people involved in developing
software and the jobs they're going to do. Requirements are
sometimes described as abstract "functions", to be described
without prejudicing design decisions in any way--in fact, without
even assuming that people will write software to implement them.
I think this leads to confusing, even silly, requirements
documents. Everything is so abstract that no one can understand
it, often not even the programmers.
I believe that it's much more useful to think of requirements as
effects that you're trying to produce by applying known software
tools and techniques. In a typical business application, you
know full well that the programmers will make a database. So go
research the information that they need to design the database,
choose a database technology, etc. Find out how many
transactions per day the users will do, find out what real-world
questions people are going to ask about the database, find out
which questions they're going to ask most and which least, etc.
When you focus on the real-world stuff, you can get a very simple
document. It talks about the matters of real interest to the
customer, and nothing more. Also, it stimulates the creativity
of all the software developers. "Oh, is *that* what they're
trying to do? Ah, I see, the data from the county recorder is
often a month out of date, but the preliminary data that's
available electronically is often inaccurate. Well, I can see
several ways that we could address that..." Now you have the
developers using their knowledge and creativity to benefit the
customer. That is the ultimate high for a system analyst!
Also, I think it helps on many projects to define those effects
in terms of the problem domain. For example, very few companies
really *want* their employees to spend all day entering data into
a computer. More typically, they want up-to-date information
about some part of the real world--say, real-estate transactions
in a certain area. So ask what real-world information they need,
and then ask how that information changes, where that information
is available from, and what sorts of problems it has with
inaccuracy or timeliness. The real requirement, then, is
"So-and-so can get such-and-such info about real-estate
transactions in such-and-such area on demand."
The distinction between problem domain and program is useful and
meaningful, though of course you have to draw the line between
"problem domain" and software somewhat differently on every
project. For a real-estate information system, the problem
domain is real-estate transactions--nothing to do with the
computer. For a word processor, the problem domain is
documents--entirely inside the computer. Most real-world
projects are somewhere in between. You don't so much ask "What
is the problem domain?", you ask, "What within the customer's
area of expertise would be useful to ask about, to give the
programmers the information they need to start designing
software?"
Is number of transactions per day "what" or "how"? Who cares?
It's information that the programmers need to know, and that only
the customer can supply.
--
Ben Kovitz <bkovitz -at- uswest -dot- net>
Author, Practical Software Requirements: A Manual of Content & Style
http://www.amazon.com/exec/obidos/ASIN/1884777597
http://www.manning.com/Kovitz
Previous by Author:
book on Acrobat?
Next by Author:
templates for design docs
Previous by Thread:
Re. Callouts on graphics in HTML?
Next by Thread:
Importance of Writing Skills
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads