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
The GNU ICQ-compatible Server
You can see their documents here
This sig is false.
Actually, you're wrong.
A proper design spec can help you with integration and maintenance. Heck, that's what it is there for. It speeds up your understanding of an application when you have to come back after a year to fix something. It also helps with OS programs, because it makes it easier for other to contribute when they have an overview of *how* the application work, and why something is done.
Je ne parle pas francais.
[DISCLAIMER: I also write Slashdot reviews.]
It's very simple. These reviews are done on a volunteer basis. Therefore, the only books reviewed are the ones the reviewer has taken the time and effort to read, and then the time and effort to review.
That tends to be books that are, in my case, excellent. I don't have time to read poor, marginal, or even "okay" books, because I have several (allegedly) excellent books on my shelf waiting to be read.
That said, sometimes I hit a dud. Then I review it as such. I reviewed a game programming book on Slashdot at 5/10 because it was mostly crap.
--
--
Marc A. Lepage
Software Developer
If you think requirements are academic, then you haven't been in industry.
I've worked at corporations that neglected requirements documents, and those that required them. The difference is night and day.
How do you know your software is correct without documented requirements you can check against? Perhaps that's not so important with OSS, where almost anyone will find a use for the software even if it isn't what was originally intended. But when your customer, and your future paychecks, are depending on meeting a market need, better than your competitors, you can't afford to play fast and loose.
Perhaps previous OSS projects were mostly little ones. They're not so bad to maintain without proper documentation, due to their simplicity. But many industry software systems are huge, with many features, legacy code, backwards compatibility, etc. You cannot just wade into the code and start hacking. It doesn't work like that.
As OSS projects mature and get larger and more complex (XFree86, GNOME, etc.), they also require a more academic/industry approach. And if you check out their web sites, you'll find that they do. You'll also find that those that don't, quietly disappear without a ripple.
--
--
Marc A. Lepage
Software Developer
>If you think requirements are academic, then you haven't been in industry.
;)
Programming in industry for 20 years (since college).
>I've worked at corporations that neglected requirements documents, and those that required them. The difference is night and day.
I used to live this delusion too. When you're old enough to look back, you'll realize that over emphasis on requirements and design cost more than they save.
>Perhaps previous OSS projects were mostly little ones.
It's the other way around: small projects benefit more from over design. Large projects never get finished because of too much emphasis on requirements and design.
I've got to stop replying to all of these now; I realize I've struck a nerve in the youthful programmers who need a conversion of consciousness. I'm afraid experience is the only thing that will help you realize the delusion
Chris
When I die, please cast my ashes upon Bill Gates -- for once, make him clean up after me!
I've worked at corporations that neglected requirements documents, and those that required them. The difference is night and day.
I used to live this delusion too. When you're old enough to look back, you'll realize that over emphasis on requirements and design cost more than they save.
"Over emphasis" on anything is a mistake. Magical silver bullets won't do your job for you, and this industry certainly has suffered through plague after plague of the damn things. So what? Your arguments sound like those of opponents of structured programming (I had a bitter argument with my uncle about goto's last year -- it was like those stories about Japanese troops in caves in the Pacific who didn't know the war was over!) and the more recent opponents of OOP. Well, sure, you can draw a cartoon, reduce something to absurdity, and make it look silly. So? Meanwhile, somebody else takes the time to learn and understand it, and to get a grasp of what it offers and what its limitations are. OOP and structured programming have both turned out to be very valuable tools. They don't do your job for you, no, of course not. They're good damn tools, but like any tool, you have to learn how to use them, when to use them, and when they're irrelevant, inappropriate, or inadequate. A screwdriver is a good tool for driving screws. You can "prove" that it's worthless by trying to use it to cut wood, but you haven't proven anything that's of any interest.
I realize I've struck a nerve in the youthful programmers who need a conversion of consciousness.
It sounds to me more like somebody growling about how "these damn college kids think they're so smart". Well, at least you didn't tell us about coding uphill in the snow both ways . . .
I've done large programs your way, and my way. My way has worked a lot better in practice. Basically, all we're saying is that neither of us would hire the other.
"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." --
Overemphasis on any facet of implementation, including (perhaps especially) requirements and design, will lead to a flawed product. (The greatest flaw is never geting done.) Finding overemphasis of the design phase is a very common problem.
The opposite problem, not enough emphasis is also prevalent. You can't simply wade in on any but the smallest projects.
Overall the real problem is finding the right balance between these extremes is the key to success. Unfortunately this balance changes with every project. As cworley said on simple projects planning til the cows come home is effective. Then again, so is wading in and hacking away.
Unfortunately there are "forces" at work making this balancing act particularly hard. Management and most consultants want the design phase to be highly detailed and documented. Management wants all this in its standard form. The consultants have their own different forms. The code jockeys want to start hacking away. These activities are the ones that directly generate income for each of these groups. There are precious few whose responsibilites cross these boundaries. As a result "failed" projects have a great deal of finger pointing. The suits say the code jockeys didn't follow "The Plan", the programmers say they coded to the available spec., but that the spec was incomplete or downright wrong.
This leads to a vicious circle where more design procedures are put in place, and where programmers are tied more and more to operating in their little areas of the code. In essence the reaction to the failure ensures more of the activity that caused the failure!!
You must seek balance in thought and source, only then a Jedi will you be.
Don't post innacurate information
If you do, I swear by my pretty floral bonnet I will end you.
>[for one client, I] maintain several hundred thousand lines of undocumented code... working without a sound-process base is irritating
>...
>For my other client, we did a formal spec and design, and finished the implementation ahead of schedule and under budget.
Two different projects in two different states of development. I bet there were (or will be) times when both perspectives applied (or will apply) to both projects.
If the second project is lucky enough to live beyond it's initial writers employment, there will be new programmers moaning how poorly the project was built... they'll find hacks, they'll find code that's contrary to the documentation as proof. They'll cast aspersions upon your mother.
Teamwork is important. Was this where the first project failed ("everybody quit or got fired")? If not, I bet when they initially wrote it, there were design & requirement specs and lots of documentation and research; they were probably proud of what they did and how they did it. Have you ever talked to one of the initial programmers about their design? If so, ask them to recall the design phase (not clouded by the day they were fired).
A small amount of documentation and research is important; but my experience is: programmers want to do R delivery is not important. Analyzing the process of analysis (writing a book on requirements) draws attention away from the reality of programming which is (or should be) spent in integration and maintenance (which they don't teach, they just say is a bad thing that can be avoided if you write more requirements and perfect the design on paper).
I've spent many years writing tools to help programmers. I've written CASE systems. I once spent six months in the requirements phase of a to-be-bloated design-by-large-commitee project (I left that company before the design phase even started).
I think every graduate knows they can write a better language.
Can they deliver an application?
Chris
When I die, please cast my ashes upon Bill Gates -- for once, make him clean up after me!
Of course not, and that's half the problem. My point is that open source projects typically don't even have an opportunity to go down this rathole. It's usually companies that want to change themselves and decide that they should buy a packaged solution from a guru.
What usually seems to happen is that some aggressive manager or wannabe brings one of these things in, to prove (maybe to themselves, I don't like to believe that they're all intentionally dishonest) that they're up with the latest technology.
Basically, my take on this (and I'm fighting the same battle where I am, where we don't use anything particularly fancy) is that the best process support programmers can give each other is to simply write everything down in a reasonably well organized fashion. I started my current job only about 3 months ago, and since then I've been making a lot of noise about the lack of process documentation and (more importantly, IMHO) writing a process document (read: web page) myself explaining how to actually build our software from scratch. My manager agrees with me, but I'm trying to work with him to come up with some way to make people understand that
Quality circles are one of the few recent fads that I actually like, because they're simple, they're based on accumulating knowledge about best practices (or rather, "what works"), and they work off of recognition. Actually, of course, they're not all that new.
I'd rather not worry about "really good" process improvement to start out with; it's better to simply take a deep breath and understand what's actually going on, and do a few simple things that people can understand that have a recognizable early payoff.
I've decided over the years that engineering is 90% common sense applied to 10% specialized knowledge. The civil and mechanical and chemical engineers have understood this all along. You don't go build a chemical plant and add all sorts of fancy wheezes and gizmos and then skimp on the operating manual, because you'll have an explosion on your hands very quickly. But software's easy and cheap to change (you can guess what my real thoughts on that matter are, both as to veracity and consequences), and if it fails maybe the machine just reboots. We also studied "computer science", so we think that our work can be reduced to formula and applied as though it's the first law of thermodynamics. What we really are is a bunch of overgrown high school hot shots who think that because we can write code that makes computers do really neat things that we're somehow better than everyone else and that basic principles of system design don't apply to us (either we can be fast and loose, or we can follow a magic cookbook and everything will turn out right in the end). Well, the old timers can teach still teach us a few lessons that they learned on the knee of their ancestors.