Hi folks, I'm putting together a little HOWTO for the GDNet software dev team that describes how to write formal requirements documents. This consists, so far, of an overview of what formal requirements are, a description of the requirements-gathering process (who does what and when), and a list of tips on writing good requirements. I'm wondering if I can get some feedback on that last part? Here's what I've got so far.

Quote: How to write good requirements For the most part, remembering to keep your requirements complete, unambiguous and verifiable will keep you on the right track. Still, there are some particular points that it can be helpful to bear in mind when putting together a requirements document.

• The phrase that conceptually heads up your requirements document – I tend to write it out explicitly – is “It has been determined that the client wishes the following requirements to be met.” Remember at all times that this is a document that the client needs to understand; they cannot reasonably sign off on the document if they do not understand what it says.
• Do not include implementation details. The way the software works internally is of no concern to the client, and by specifying implementation details as part of the formal requirements you are reducing the amount of freedom the team has.
• Check always that the client is not specifying a requirement that could be more general, particularly if the client is technical. As an example, the NeHe news system initially had something like “must cache news items for display.” In fact, the actual requirement was “the NeHe front page must look correct in the absence of the database server.” By taking the more general requirement, the implementation was now free to use an alternative approach (such as an include file generated by a cron job). Even if it seems like there is going to be no other way to implement something, by providing the ‘base’ requirement you’re ensuring that should a new way become apparent in the future, the requirements will not prevent you from using it.
• It’s often pertinent to include performance requirements – but the only one that really is visible to the client is the page generation time. To a large extent, other performance constraints – such as number of database queries, or volume of data transferred – will be implied by the page generation time, because they all contribute to it. The other thing to consider is things like hit rate – if you’re working on changes to an existing page, you can measure the hit rate at the current time and use it as a requirement (i.e. “page must be able to handle XXX hits per minute without page generation time rising over 0.5 seconds”). Don’t say “solution must be performant,” because that’s not verifiable – give some figures and say “solution must be at least this performant.”
• It is preferable to provide background information on a requirement where it would aid understanding, in the same way that you’d comment code. However, it is good practice to separate such information from the requirement itself. Beware of phrasing such as “the software must do X because Y.” Just say “the software must do X” and explain Y in a sub-point.
• It’s OK to state a requirement as “this is acceptable” – i.e. the solution can, but does not have to meet it – as it clarifies that the reverse is not true.

Anything I could add to that? Anything that should be changed?

A requirement must be verifiable, or at least it must specify a way to verify that it has been met.

My thoughts:

Implementation Details
The requirements doc should not include implementation details. However, this is very different from saying that one should not pay attention to implementation while doing requirements.

Fred Brooks put it nicely: your requirements specifiers (architects, in his terms) should always have a rough idea of how to approach the implementation of the things they design. However, they shouldn't even bring up their concept unless it is specifically solicited by a programmer who is responsible for implementation.

Designing and specifying a system without paying any attention to implementation is very dangerous. However, that implementation should not be transparent to the client (in most cases, unless you're doing APIs or something), and it should not be written in stone until the team actually starts working on the project.

Once the spec is signed off, the next important step is to plan out how the team will implement the spec, so it is very useful at this stage to at least have some rough high-level ideas of the various options and their tradeoffs.


General Requirements
Be careful here. Sometimes you can have (or create) requirements that are too general. It's hard to detect these without a lot of experience, but a good rule of thumb is that if a requirement ventures into "Do What I Mean" territory, it's too vague.

I don't really know of any other highly useful questions one can ask oneself about whether or not a requirement is broken; I seem to do it by intuition most of the time. But IMO it's definitely something worth careful consideration.



Looks like a great start, aside from that... heck, I think it'd be cool if you generalized this a bit when it's done and did a published article. Writing good requirements is something every programmer should be able to do, but most are totally unfamiliar with.

Quote:Original post by JohnBolton
A requirement must be verifiable, or at least it must specify a way to verify that it has been met.

Aye; I consider verifiability to be part of the definition of a "formal" requirement, so it's covered quite extensively in the "what is a formal requirement" section, and is reiterated in the first sentence of this section [smile] Thanks, though.

Quote:Original post by ApochPiQ
Implementation Details
The requirements doc should not include implementation details. However, this is very different from saying that one should not pay attention to implementation while doing requirements.

Yes, absolutely. Another part of the document describes the requirements-gathering process - who does what and when - and it includes an RFC period with the entire dev team and a signoff by the technical lead. If the doc gets as far as being signed off, it's been reviewed for technical feasability.

Quote:your requirements specifiers (architects, in his terms) should always have a rough idea of how to approach the implementation of the things they design. However, they shouldn't even bring up their concept unless it is specifically solicited by a programmer who is responsible for implementation.

The personnel model I'm advocating (unrelated to formal requirements) is a 'pool' model in which nobody specializes; the result will be that anyone acting in a Requirements Engineer role will also have done work as an implementor (and may even end up implementing their own requirements, though not necessarily), so it's likely that it would be difficult to get people not to at least think about the implementation [smile]

Quote:Designing and specifying a system without paying any attention to implementation is very dangerous.

Well, it depends on whether you're willing to deliver a product with a note attached that says "the following requirements could not be met." I'm not willing to do that, though, so I agree with you.

Quote:However, that implementation should not be transparent to the client (in most cases, unless you're doing APIs or something), and it should not be written in stone until the team actually starts working on the project.

I'd consider requirements engineer as after "starting work" on the project, but yeah, I agree. What I'm envisioning is that after the requirements doc is done, a solution design doc is created (i.e. a description of a system that will meet the requirements) including mockups and suchlike, and then an implementation plan, and only then will anyone actually begin writing any code.

Quote:
General Requirements
Be careful here. Sometimes you can have (or create) requirements that are too general. It's hard to detect these without a lot of experience, but a good rule of thumb is that if a requirement ventures into "Do What I Mean" territory, it's too vague.

If it ventures into that kind of territory then it's likely not verifiable or clear, so it fails as a formal requirement.

Quote:I don't really know of any other highly useful questions one can ask oneself about whether or not a requirement is broken; I seem to do it by intuition most of the time. But IMO it's definitely something worth careful consideration.

Aye, what I'm looking to do in the long run is train up a bunch of people with the skills and intuition they need to write formal requirements, without having to refer back to things like my HOWTO. It's sort of on-the-job training.

Quote:
Looks like a great start, aside from that... heck, I think it'd be cool if you generalized this a bit when it's done and did a published article. Writing good requirements is something every programmer should be able to do, but most are totally unfamiliar with.

Thanks. I'll think about the article... I'd be happier if I see it getting implemented in the team first so I can check that it actually works [smile]

When you write formal requirements the wording is important for legal reason if it becomes binding part of a Statement Of Work (SOW).

The word shall is used to indicate a binding requirement the contractor is obligated to implemented. The word must is used to describe events or circumstances that result from adhering to other requirements (other shall statements) that do not need to be independantly verified. The word will is used to describe immutable laws of physics or logic that cannot be violated.

e.g.

The uber egg carton shall provide protection to achieve a <00.0001% break percentage when a full carton is subjective to the test conditions detailed in Appendix I, Test Procedure A.

Appendix I
Test Procedure A: Uber Egg Carton Free-Fall Test
1) Place 12 certified AAA eggs in the uber egg carton
2) Drop the uber egg carton from a height of 12' +/- 1".
3) The uber egg carton will fall with an acceleration of 9.8m/s2.
4) All twelve eggs must survive this test 83,333 times out of 83,334.



There are several levels of requirements as well. Only the very high level system requirements to do require specific implementations. Derived requirements for mechanical components, electronics, or software will start to contain design requirements. For software, they may require particular a database to used, they require certain operating systems, they may require a specific language, specify states & modes, and even require certain key objects or modules.

In some circles there is a lot of emphasize on not specifying details in the requirements, but that counter productive to a certain extent. If you know what you want, write it down. The contractor/implementer is always free to suggest something better and implement with your agreement and change of the SRS (Software Requirements Specification). If you do not want the implementation detail to be binding, then you can write a general shall statement follow by an example implementation. The keyword for that is may.
Like most things software, this is entirely arbitrary and the goal is not uber general nor uber specific but the sweetspot that matches what is truely needed (not desired).

Extreme Performance Wall Stud Finder Software (XPWSFS)

The XPWSFS shall respond to the leading edge of the proximity pulse sensor within 250us by driving the LED output High.
The XPWSFS may use an external interrupt to accomplish this task.

We have no justification for a 250us response time, the user will never know the difference if it happens within 25000us.


Good high level requirements will include a justification section about why the requirement is necessary and/or what the collective goal is with other requirements. Using superpigs NeHe caching example, if they justified it they would have realized the real requirement was to survive when the database was not present because they would have had to answered why it needs to cache.



As a general flow:
System Functional Requirements
Software Requirements Specification
Software Architecture & Design

There are of course many variations.

Quote:Original post by Shannon Barber
When you write formal requirements the wording is important for legal reason if it becomes binding part of a Statement Of Work (SOW).

The word shall is used to indicate a binding requirement the contractor is obligated to implemented. The word must is used to describe events or circumstances that result from adhering to other requirements (other shall statements) that do not need to be independantly verified. The word will is used to describe immutable laws of physics or logic that cannot be violated.

e.g.

The uber egg carton shall provide protection to achieve a <00.0001% break percentage when a full carton is subjective to the test conditions detailed in Appendix I, Test Procedure A.

Appendix I
Test Procedure A: Uber Egg Carton Free-Fall Test
1) Place 12 certified AAA eggs in the uber egg carton
2) Drop the uber egg carton from a height of 12' +/- 1".
3) The uber egg carton will fall with an acceleration of 9.8m/s2.
4) All twelve eggs must survive this test 83,333 times out of 83,334.

Brilliant! I'd like to be able to pretend that our requirement docs are legally binding so I'll adopt that approach. Thanks!

Quote:
There are several levels of requirements as well. Only the very high level system requirements to do require specific implementations. Derived requirements for mechanical components, electronics, or software will start to contain design requirements. For software, they may require particular a database to used, they require certain operating systems, they may require a specific language, specify states & modes, and even require certain key objects or modules.

Aye. At the moment I'm just focusing on the document that gets presented to the client - and is thus inherently non-technical - but I'm aware that once those are done you'll start constructing increasingly low-level documents until you're operating at a code level. Things like the database to be used or the language to write it in are part of what I'd call the 'Implementation Plan,' which is couple of levels down from the user requirements.

Quote:In some circles there is a lot of emphasize on not specifying details in the requirements, but that counter productive to a certain extent. If you know what you want, write it down. The contractor/implementer is always free to suggest something better and implement with your agreement and change of the SRS (Software Requirements Specification). If you do not want the implementation detail to be binding, then you can write a general shall statement follow by an example implementation. The keyword for that is may.
Like most things software, this is entirely arbitrary and the goal is not uber general nor uber specific but the sweetspot that matches what is truely needed (not desired).

Extreme Performance Wall Stud Finder Software (XPWSFS)

The XPWSFS shall respond to the leading edge of the proximity pulse sensor within 250us by driving the LED output High.
The XPWSFS may use an external interrupt to accomplish this task.

We have no justification for a 250us response time, the user will never know the difference if it happens within 25000us.


Good high level requirements will include a justification section about why the requirement is necessary and/or what the collective goal is with other requirements. Using superpigs NeHe caching example, if they justified it they would have realized the real requirement was to survive when the database was not present because they would have had to answered why it needs to cache.

OK. I think the way I may want to approach this is to establish a seperate 'notes' section that mirrors the requirements; any justifications or implementation suggestions can be put into that section.

Quote:
As a general flow:
System Functional Requirements
Software Requirements Specification
Software Architecture & Design

There are of course many variations.

Aye. What I've got at the moment starts with business requirements analysis and functional spec, built with the client's cooperation; then the spec is taken into the team and internal technical requirements are built (basically by cross-breeding the functional spec with the systemwide characteristics spec). Then an overview architecture&design doc for the solution is created, stemming off into seperate docs for UI design, implementation plan, scheduling, etc.

My 2 cents:
You might want to distinguish functional requirements (the main character wields a sword) from nonfunctional requirements which adress quality requirements such as:

performance: the game shall run at 60fps

flexibility: we should be able to change 3d engine with little effort

security: the map will be stored on the server instead on each local computer

scalability: our MMORGP can serve up to 1 million users simultanously

usability: players should be able to learn the controls of the game in less then 10 minutes

accessibility: the game shall have support for captions and configurable controls

A lot of game designers don't care about NFR's and that is also the reason for most games being very low quality. NFR's can be further distinguished in user oriented qualities (performance, usability etc) and organisational qualities (flexibility, maintainability)

A formal requirement is very different from a formal specification, which is what I believe you are referring to snk_kid. Formal requirements are generally written in natural language and may be accompanied by some techincal diagrams or refer ti additional techinical references.