Slashdot Mirror
Practical Software Requirements
Background
Greetings, all. I apologize for my long review layoff, but between June and now, I've managed to acquire a job where I actually have something better to do than write book reviews! Bonus! :-) Regardless, in the course of designing a new system for my company, I needed to write a good requirements document. I thought I knew how to do this, and set about creating the most anal, unreadable piece of technical gobbledygook you've ever seen. Needless to say, this document didn't fly. In desperation, I fished around Amazon.com for some decent requirements books. I already had the IEEE specification for requirements, but I didn't have a book that explained how to use the specification (this should tell you something). My search finally turned up this work, which had some good reviews posted, and the rest is history....
What's the book about?Kovitz presents a very different view of requirements engineering from the prevailing view. Most approaches to requirements focus on breaking a problem into parts, and with these parts filling in predefined sections of a requirements template. Kovitz disagrees with this approach to requirements, and offers his own. In short, he says that decomposing a problem correctly is hard to impossible without some idea of what the solution is before you begin. Thus, when presented with a problem, you should try and find out what type of problem it is, so that you can relate the problem to ones already solved. From here, Kovitz describes how best to frame problems, and gives some sample problem frames.
Of course, once a problem has been placed in its proper frame, it still must be broken out into its constituent parts so that the requirements can be enumerated. Kovitz describes a process for doing this whereby the denizens of the problem domain are enumerated, along with their relationships. Once these denizens ("sets") are enumerated, along with their individual attributes and relationships, they make up the description of the problem domain. The requirements, then, are the effects the machine is to produce on the previously-described problem domain. Kovitz also advocates a separate interface document, which describes how the machine interacts with the problem domain. The book then ends with a series of chapters on style and structure, and a comprehensive example.
What's Good?Overall, I found the book to be quite excellent. Kovitz tries to break down the legalistic view of requirements engineering as a top-down fill-in-the-blank exercise, and instead advocates a more flexible system whereby the design is kept separate, but each project has the process attuned to its distinct needs. This is quite a refreshing view, but one that still mandates good software engineering practices that can get any project off to an excellent start. In addition, the author has an online discussion forum where readers can ask questions, and receive direct help from the author. I found this to be an excellent resource, and the author is to be commended for such participation and dedication.
What's Bad?I have to admit, I had a little trouble applying the ideas in the book. Specifically, I had difficulty deciding what exactly were "sets" in my problem domain, and what their attributes were. It was a simple issue of translating the concepts to the reality of my project. In the end, I don't think my requirements document quite met the standard set in PSR, but it certainly benefitted a great deal from it.
So What's In It For Me?I haven't been able to give a good software engineering lecture in a while, so I'll jump back on my high horse. All project, especially open source ones, need the solid foundation that can only come from good requirements. If you don't know what you are going to build, you have no chance of building it. Open source projects especially need a paper trail for new participants so that they can quickly come up to speed and understand the direction that the project is headed. Artifacts such as requirements speed this process and give everyone a common framework to draw from. Kovitz's approach provides for readable, coherent documents that allow people to understand what domain they are working in, and what they are trying to accomplish.
Purchase this book at Amazon.
- Table of Contents
- Introduction
- Acknowledgements
- Author Online
- Part I: Groundwork
- Problem Solving
- Problem Defining
- Two Worlds and Three Designs
- Problem Framing
- Five Problem Frames
- Multi-frame Problems
- Part II: Content
- Software Development
- Two Documents
- Classes and Relations
- Sequences and Events
- Causation and Control
- Special Topics
- Part III: Style
- Documentation
- Organization
- Small Details
- Part IV: Examples
- Bug Log Requirements
- Bug Log User Interface
- Glossary
- Bibliography
- Index
but if so, i'm a goober
I enjoy reading the reviews on slashdot quite a bit, but from time to time, I wonder why they are all positive. It's certainly not the case that all books that are read by slashdot readers are good.
Sometimes newspapers and such will never write a negative review mostly because they were sent free books for review and promotion by the publisher and it's somewhat implicit that they'll get a good review. I'm pretty sure that that's not the case on slashdot, but why do all the books get good reviews? Is it the old adage of "If you don't have anything nice to say, don't say anything?"
I'm not accusing anybody of anything. (Sometimes it's a bit weird how whenever you say anything on slashdot that could possibly be taken the wrong way, you have to qualify it with 1 dozen disclaimers) I'm just wondering about it out loud and wondering if anybody else has any comment on what seems to be the trend.
I would personally like to see some high profile books that suck be mentioned as such, so I can avoid them.
-- Truth goes out the door when rumor comes innuendo. -- Groucho Marx
I think the main thing is that there's so many good books out there that people want to highlight the ones worthy of acquisition, rather than waste thier time slogging through (and afterwards painstakingly deconstructing) a steaming pile of dead tree barely fit for the recycling bin.
Anyways, bad reviews are on the way, rest assured. And at the end of each one I write, I'm going to append: "I blame Hemos for this book. If he didn't send it to me, I wouldn't have felt obligated to wallow in it's suckitude just to write a reasonable review.". >B)
--
rickf@transpect.SPAM-B-GONE.net (remove the SPAM-B-GONE bit)
"People will pay big bucks for the luxury of ignorance."
Can anyone point to an example of an OSS project using a requirements document? Presumably this would be posted on the web somewhere so everyone can see it? If so, was the document kept up to date and was it useful?
The way to develop software is to find some open source code that does most of what you need, modify it to do the rest!
The problem with any approach that focuses on requirements, design, and style is that it doesn't help those software development lifecycle stages where software spends most of it's time: integration and maintenance.
Another academic approach for rocket scientist wanabees! Nothing to do with practical programming.
Chris
When I die, please cast my ashes upon Bill Gates -- for once, make him clean up after me!
The GNU ICQ-compatible Server
You can see their documents here
This sig is false.
Thanks Jason, for the informative review.
I also started a new job this year, and had the pleasure of sitting down to write proper requirements documents for new software systems. This was something I did not have the opportunity to learn or practice at my previous job.
We too found ourselves running out to our neighbourhood book store, to find good books on requirements documents. We ended up with info from McConnell books, and a requirements lexicon by Michael Jackson.
Really, we knew the theory, but just hadn't had the practice. Now, after going through a round of requirements, revisions, etc., the process is a lot clearer. I'm a lot more comfortable with it.
Another thing we found helpful, is to try to write testing documents based on the requirements documents, before writing the design documents.
--
--
Marc A. Lepage
Software Developer
We're waiting for Katz to publish. :-)
The other comments forgot an important point. Yes, a spec can help maintainers understand the architecture one's it's been implemented, and that's very valuable, but it's more valuable to start with a clean, coherent, consistent, and adequate architecture. This is CS105/Free Brooks[1] stuff, but nobody ever seems to believe it until they learn it the hard way. God knows I didn't. Some people never learn it at all.
IMHO most programmers have no business initiating projects. Architecture is not the same as coding. It's a lot harder, and most of us just don't find it "fun" enough to do it well. It also requires a lot of painful experience to know how far to go, when to stop, what to leave vague, what to allow for, etc. "When to stop" is crucial.
The way to develop software is to find some open source code that does most of what you need, modify it to do the rest!
Yeah, but most really interesting projects have to start from scratch, and not all projects will benefit from repeating old mistakes ad infinitum. Furthermore, have you ever wondered where that magical free code came from? Somebody wrote it. It's not turtles all the way down. Somewhere, at some point, somebody started with an empty text file. If the code is worth reusing, odds are good that your mysterious benefactor spent some time thinking before s/he started hammering out for( ) loops. The alternative is to spend your days grafting a heterogeneous flock of kludges and patches onto an inadequate foundation.
Another academic approach for rocket scientist wanabees! Nothing to do with practical programming.
I'm left wondering if you've ever done any practical programming that was of any worth. If you want a good example of a program that grew by accretion rather than by design, try Windows. "Design" may seem like "eating your vegetables", but you can't blow it off if you're doing something non-trivial. IIRC there's been at least one major shake-up in the Linux kernel tree to correct for early short-sightedness.
Programs don't exist. They're soap bubbles made out of zeroes and ones. In hardware engineering, the blueprint describes a thing that has an independent existence. With software, the code is the blueprint, and the blueprint is the thing. Software is the Word made Flesh. It exists entirely in the Platonic realm, so there is very little meaningful distinction to be made between "theory" and "practice".
--------------------------------------
[1] Read The Mythical Man-Month by Fred P. Brooks. It does for software "engineering" and software project management what K'n'R does for coding per se.
"Once a solution is found, a compatibility problem becomes indescribably boring because it has only... practical importance"
"Christianity neither is, nor ever was a part of the common law." --
i;ll wait for the moovie to come out
I also found PSR well-written and very helpful. It described formally many practices which I had been trying to understand intuitively. It offers a very clear way of explaining what is expected of a piece of software. It also offers some guidance on elicting requirements from users. In a similar vein, I can recommend the guidelines of the Extreme Programming group (http://c2.com/cgi/wiki?ExtremeProgrammingRoadmap) .
What I've typically seen happen is:
1) Company goes along producing software
2) Company tries to do too much and winds up with feature-packed garbage that's eons late and getting later in real time.
3) Company gets religion about engineering standards and practices and tries following the methodology de l'heur.
4) Next release is just as bad, partly because everyone has been fumbling over methodology.
5) Everyone forgets the good intentions altogether and goes back to the usual chaos
Note that this doesn't strictly have to apply only to commercial software, but open source projects typically don't have the money to go out and buy the fancy stuff. Also, there aren't many open source project leaders who could force that kind of nonsense on unwilling engineers.
As I read the review, though, this book isn't advocating that kind of approach; it sounded more like an iterative kind of thing that in practice is the only thing that can really work.
Many of them. Search freshmeat for the specifics.
... is one that IMHO is not worth the time/money. I was frankly amazed that this one made it through the O'Reilly editorial process in its current form. As (I believe) someone on Amazon said, it looks like someone's PowerPoint slides on UML slapped into an O'Reilly cover.
> 2)Your boss usually wants to keep that code (that he paid for) to themselves. Let's face it, that project probably took 4-5 man years, and cost him (Fully loaded costs), in the order of 1 million dollars. You don't GIVE that to you competition for free, or you go out of business, fast
So, Open Source has no business models?
You need to convince yourself and your boss that software is a service, not a product. Even Balmer said that a few weeks ago (in his "how to eat your golden-egg-laying-goose" speech).
Unless (or, maybe, even if) you're a large company with market share, that code you spent $1M writing will soon be lost forever. You'll have wasted your time and your bosses money.
Name any large, currently popular, application, not written by a large company, whose code dates back over 5 years. Only Open Source lives and evolves, unless you're M$ and your customers will blindly buy whatever you sell.
Chris
When I die, please cast my ashes upon Bill Gates -- for once, make him clean up after me!
And coming in February, Geeks : How Two Lost Boys Rode the Internet Out of Idaho .
Apologies to the /. crew that the links above do not include the secret code that would generate a kickback for them.
Bravery, Kindness, Clarity, Honesty, Compassion, Generosity
...Nothing interesting here. Just move along...
Chris,
This works for commercial software, but most software out there isn't commercial software. MOST software is things like an application to process an insurance claim, and tell the adjuster how likely a jury is to make an award. Or to tell you what is going to be on the evening news 15 seconds from now, and how long that segment will be.
Yep, it's a service, to ONE company, that has the companies business rules built in. You never sell the thing (it may be charged back)
When I say that the software goes no where, I'm not only talking about the source, but even the EXEs.
-- 73 de KG2V For the Children - RKBA! "You are what you do when it counts" - the Masso