In a specification, should I describe what a product does (ideally) or what it should/must do?

Question

I'm writting a German specification (I'm not German).

Differences may appear for this process in different cultures, especially in the terminology, but usually here's the idea:

• The client writes his needs and wishes in a document, called a scope statement or requirements document.
• The supplier tries to understand the actual need of the client (which might be different to what was written and to what the client meant to say and to what the client thinks he needs, etc.)
• The supplier writes a specification for the product, which should fill the client's need.
• The specification needs to be precise enough for the product to be made (ambiguity problems occur).
• The client and the supplier can check whether they have understood each other, and discuss details of the product.
• The client agrees with the specification (or at least its current iteration) and the supplier is ready to start the work.

(it may of course be expected of you to disagree with this process, but this is irrelevant to my problem):

I'm now somewhere around the last two steps and I've been criticized because I wrote what the product must do, and not what it will do ideally.

Usually along the lines of

The product must be able to perform task A

And I was expected to write

The product performs task A

This is a simple word play, but I feel saying what the product does, while the product isn't even on the way to be made yet, is wrong. I would tend to consider a specification as a contract of what the product is expected to do (what it must do and how it should do it), and not what it does.

Said differently, I feel this is the specification and not the manual of the end product……

Should I say what the product must do or what it does?

Answer 1

This flow of events is very similar to what I work with. However, there are differences in terminology that I think may be causing some issues.

What the customer provides isn't a requirements document. It's likely to be a vision document or a concept of operations (CONOPS). These documents could call out the major features of the system, but they are written from the perspective of the customer or user, though, and tend to not be as technical (although they could be if they are coming from a technical customer or user) or as unambiguous as a design engineer or quality assurance engineer need to carry out their work.

Often, these documents tend to describe the customer's goals for the system - how they intend to use it, what they want to accomplish, and so on, but in their business language, using business terminology and concepts. This type of content is likely to not be suitable to the engineers building and designing the system, so it needs to be transformed.

Engineers will take the customer's inputs of a vision document or CONOPS (what you're calling a requirements document) and create a requirements specification. This is a formal statements of the functional and non-functional requirements, the quality standards, any design constraints, and use cases in a way that can be understood by the rest of the design. implementation, and test team. Regardless of the structure and format of the customer's input, the requirements documented in the specification should have the characteristics of a good requirement:

• Each requirement addresses one thing (cohesive)
• Each requirement is fully stated in one location (complete)
• There are no contradictions between requirements or between a requirement and some external document (consistent)
• Each requirement does not contain conjunctions, such as "and" (atomic)
• Each requirement can be linked to a business need of one or more stakeholders (traceable)
• Each requirement is not obsolete (current)
• Each requirement is clear, acronyms are defined, is objective, avoids negative statements (unambiguous)
• Each requirement makes it clear as to its importance
• The implementation of each requirement can be determined through inspection, demonstration, test, and/or analysis (verifiable)

This document is the requirements specification for the product. It states exactly what the product must be able to do, when it is finished. If you have optional requirements, then those are clearly identified as optional and state what the project should do or may do. This is where the idea of writing requirements as "shall" statements come from. Optional requirements would replace "shall" with "can" or "may", and the meaning of "shall", "can", and "may" should be defined in the document so that the designers, implementers, and testers know the relative importance of each requirement.

By defining exactly how the product must behave, you are essentially providing instructions for the designers, testers, and (to some extent) implementers. They are starting with a system that does not yet accomplish all of the things and are being told what the thing is going to do when it is done. The design and implementation can be compared (in various ways) to this specification to ensure that it fully complies with what the customer intends.

Answer 2

Everybody has there own style, and at the end of the day, it's best to "dance with the one what brung you", (do what the person that's paying you says to do).

Having said that, I feel that it's all a question of abstraction levels and audience. Let's suppose this is a chip design. The answer below will apply equally well to software with the specific examples changed to meet the vocabulary and context of the day. OK, back to levels of abstraction.

You should use 'must' statements when specifying a constraint for the system designers and the verification/testing engineers. Consequently, you might see the following in a specification:

The SRAM buffer will have a throughput of at least 8 Mbits per second, and must be implemented using 9 nm CMOS technology compatible with the TSMC fab.

Translated, the specification writer wrote about the portion of the design where the designer is expected to exercise his craft/creativity, (the throughput o the buffer), in more relaxed terms than those used for the fabrication process where there is no wiggle room.