Good Practices for Writing Project Requirements

I'm looking for input on writing clear, professional, and thorough project requirements.

After some quick googling, I have yet to find a good resource of standards or even good practices for writing project requirements. I have been talking more and more about projects with friends in remote locations and it is more important than ever to ensure clear communication.

Does anyone have any advice or guidelines for good writing practices for project requirements? Or even better, any online resources to look at?

I'm thinking about everything from block diagrams to schedules and timelines to use cases, project pitches and overviews.

Any input is greatly appreciated!

My Dad taught me to write. Basically put everything you can think of down on paper, then be ruthless in culling anything that isn't pertinent. The end result usually says exactly what you want it to.

Excellent question, washer. There's probably no one-size-fits-all answer. My interpretation of "requirements" is that you want to make a written specification of what a particular project is and isn't so that it can be implemented by different people, sometimes geographically and temporally separated. This is a difficult task, for a variety of reasons. There's also the tension between trying to make the document complete and self-contained (which tend to make it long) and the ability of users of the document to extract all the needed information to do their jobs well, even if it's buried in hundreds of pages of dry prose. Then toss in the complication of working with folks to whom your language isn't native.

These documents are difficult to write (bit I repeat myself ). The person writing naturally is influenced by the state of the art at the time. The desire is to describe the thing to be developed from an outside view (some people use the term "external reference specification") in terms of how it feels, tastes, behaves, etc. For the most part, implementation is ignored. In the business world, the attempt is to describe the customer's experience. Of course, this is modulated by practical needs, such as the need to use a particular internal tool or technique.

In my industrial experience, requirements were often generated using the documents from well-regarded previous projects as templates and guides. More importantly, the documents needed to be written by the most experienced and knowledgeable people, with input from a variety of sources. Part of the reason for this is that the "newbies" won't understand the variety of things the project could touch or be touched by. These requirements documents also tend to be dynamic, even during implementation, as no one's foresight is perfect.

The writer(s) of the requirements also need to keep the needs of the consumers (customers) of the document(s) clearly in mind. It's a sin to not put enough in as well as too much. The first leads to a poorly-defined project and the latter leads to something that doesn't get read or used. Thus, the needs of the requirements depend on the project itself, how many people are involved, the competence levels of the folks involved, and how many levels of people are involved. For example, a document for 5 engineers who are going to implement a hardware/software project is different from one that will go up the chain to be reviewed by a VP, marketing, and manufacturing. Clearly, the document writer(s) need to know the needs of the consumers and act accordingly.

Some suggestions for further places to look:

* Search IEEE, ANSI, ASME etc. for likely documents. You may not find exactly what you want, but it's likely you'll find bits and pieces.

* Go to a library and have a librarian help you search. This is a better resource than just typing a few terms into a search engine as the good ones are trained in searching and have wide experience (I had the luck to work with some good librarians, who are under-appreciated professionals).

* Look under project management resources, such as professional organizations. I have a friend who joined such a thing and she once told me they had some good resources available.

* Check software engineering resources -- again, for ideas and templates, not complete solutions. McConnell's Code Complete might be worth taking a look at. Even if you're not a software person, you'll be able to use many of the ideas.

* See if you can locate good examples of old requirements documents.

Finally, realize that a good requirements document isn't enough to ensure success. A project/program needs good management, good visions, good people, good ideas, and good resources to get good results.

Thank you both so much for the awesome responses!

I have been weighing the difficulty of using vague, flexible wording or being too restrictive and including too much info. This is just a project among friends, so there aren't many concerns with deadlines or contracts. We just need to have the necessary information and be clear with it, so I don't want to flood my friends with lots of wording or extra info. That being said, I think we might end up needing multiple, smaller documents. A wide-view, customer-oriented requirements document and then one or more design documents detailing the solutions for the system.

Thats a good way to go. Also, in the beginning you should all agree on the outline you will follow for technical communication. I have found it helps quite a bit to get it out of the way in the beginning.

Right now I am in a bit of a holding pattern. I'm trying to install Visio on a Windows partition but don't have quite enough space...

Does anyone know a good Mac alternative? Otherwise I'm going to have to wait to repartition and do a fresh install.

retched said:

Thats a good way to go. Also, in the beginning you should all agree on the outline you will follow for technical communication. I have found it helps quite a bit to get it out of the way in the beginning.

Click to expand...

Agreed.....