Requiements, Design Documents

[Jim Bassett]

I would like the views of other developers who have to create Requirements and design documents as well as write the code. In my company we have to write the requirements for a software product, have the requirements reviewed by numerous persons, making changes here and there that have no effect on the final product. For example, for one particular person we may have to rename the name of certain functions, or maybe create a glossary of terms to cover how each of the reviewers understand a definition of a given item. I have found that alot of time and effort goes into these documents yet all of the developers I speak to believe the time and effort would be better spent prototyping and.use this as a method of development. Any comments would be nice.

Thanks

Jim Bassett

[Bob Clarke]

Your question covers more than one issue. Any sizeable project can benefit immensely by having written requirements so that what is needed is understood by all, and that nothing extraneous gets into the project to waste time and cause needless integration problems. And peer review of requirements and design is important. But having to rename functions borders on the absurd if the group has programming standards in place (such as "function names shall clearly state what the function does, such as CalcLiquidity()"). As long as the standard has been met, the rest is just differences in style that should not be subject to discussion.

The glossary of terms also sounds like overkill unless you're bringing in people who don't know your line of business. For example, if you're writing a program for the commodities industry, then terms such as "long," "short," "margin", "roll" and others need to be defined somewhere, but it doesn't necessarily have to be the project documentation. In fact, I would lean toward not having that sort of information in the project docs, but just have a reference paragraph that tells readers where to go to get more detailed information. It is not the job of project documents to explain details of the business, but just to describe what the business rules are and how they have een implemented.

[Alessandro]

Hi.
My experience is that documentation is a very important part of design.
I feel that the important topics a good documentation should cover are:

1.- scope of the project;
2.- scope of each module in which the project is divided;
3.- interface between modules;
4.- common programming rules (i.e. name conventions and exposing interfaces).

All the rest can easily became only a waste of time, starting endless debates on any small single notch of the project.

Have a great day,

Alessandro Tripiccione

Why do we hide from the police, Dad?
Because we use vi, Son. They use emacs.

[Tomaz Stih]

Hi Jim.

Your message is very general. It is impossible to reply to it as a whole in simple terms.

1. Choosing a development process model (such as prototype model, Boehm spiral, waterfall model) depends on several factors:
- software you are developing,
- your work environment and
- knowledge of problem.
Typically you use prototype model for unknown problems and waterfall model for well-known problems that is well defined problems. A combination is possible to break your problem to managable units.
You use Boehm spiral model when there is a need to manage risk - for example if the customer can't decide about the extent of of the software or the customer would prefer result oriented insight into project instead of activity oriented insight meaning that you have to produce some usable software quickly. In this case you range requirements and implement main in small product which you then upgrade using OO techniques. Before every upgrade you estimate risk. This way the price of the software rises in steps and visible results are available after each cycle. Of course mastering Boehm spiral (one could get tempted to name chaos Boehm spiral!) requires a lot of A&D skills.

2. Documentation is essential part of project. My advice is - make no compromises! It is possible, however to make documenting process more efficient. First by standardizing documents (such as requirements, using UML for analysis and design) and second by automating some tasks such as generating documentation from your code using apropriate tools...
This will be a tough one at the beginning but I belive there are benefits once you have your process optimized.

---------------------------------------------
Tomaz Stih, B.Sc.CS tomaz@nameco.com
Ob sotoccju 10 Nameco Group
SI-1000 Ljubljana http://www.nameco.com
Europe

[kitng98]

It is definitely well worth the time spent.
Of course, all these can be "abused". In my last company, the peer reviews and critics took only at most 1 hour (over lunch) and as a result of the process, the project was finished well ahead of time ($$Bonus$$).

What we concentrate on during the peers reviews is the logic and resuse of existing codes segments, not function or variable names. Of course, we do have our inhouse naming conventions/standards that we all follows.


To be or not to be ...