1

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?

  • PS: Replace "client" and "supplier" by "customer" and "vendor" if you will. – Pierre Arlaud Aug 20 '14 at 13:39
  • How can you say what the product does if you haven't made the product yet? This does sound familiar to how I deal with requirements: a customer provides a concept of operations (how they intend to use the system, what they do with it), that's turned into a technical system specification that's flowed down into subsystem and component requirements that are used to create a design and then the design is realized in an implementation. Because this particular instantiation of the system doesn't exist, the requirements are what the system must do, so that you can see if the system actually does it. – Thomas Owens Aug 20 '14 at 13:43
  • @ThomasOwens this is more or less what I said: it doesn't exist yet, it doesn't do anything. Yet I've been told this is closer to a wish (we "would like" this) and makes it look (not according to me) like a requirement document and not an actual specification… – Pierre Arlaud Aug 20 '14 at 13:48
  • 2
    I don't understand your differentiation between a requirements documents and a specification (unless I'm misreading something). A requirements document is a form of a specification. You can have a requirements specification (the formal set of requirements that will be satisfied by the product), and then you create a design specification (the formal design that will be realized during implementation). You can have optional requirements in a specification. – Thomas Owens Aug 20 '14 at 14:08
  • 1
    I think I have enough to write an answer. When I'm done, feel free to leave a comment or ping me in chat if there's something I'm misunderstanding or isn't clear once I post it. – Thomas Owens Aug 20 '14 at 14:13
4

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.

  • I agree with all that, wasn't sure about the English terminology (it's * Cahier des charges / Spécification * in French, and * Lastenheft / Pflichtenheft *). Yet I feel you are avoiding the problem. My requirements are constructed to be atomic, cohesive, complete, consistent, current, traceable, verifiable and unambiguous. When you say "Regardless of the structure and format of the customer's input", do you mean to say that my customer doesn't get to say whether it should be "it must do" or "it does" that my customer doesn't have a say in the way things are expressed as I'm the expert? – Pierre Arlaud Aug 20 '14 at 15:06
  • When you say "By defining exactly how the product must behave", I feel I'm on the right track, because by saying "it must do" I am describing how it should behave, and not how it behaves (in an ideal world). – Pierre Arlaud Aug 20 '14 at 15:08
  • 1
    @ArlaudPierre Your customer defines the format of their input. Ideally, the actual transformation (what I'm calling the requirements specification) should be in a format that's usable by the engineering team. If you and your team think that it should be expressed using "shall" and "should" and "must" statements, then yes, that's how it should be structured. I've never seen a requirements specification as a customer deliverable item, so I've also never seen a customer that required a specific format. – Thomas Owens Aug 20 '14 at 15:26
  • Now, you could have a customer that is trying to mandate a specific format, however that becomes a point of negotiation. It would arguably be easier on the design team (and a more effective use of time and money) if you could transform their input document into a more usable format as part of requirements engineering, in order to reduce project risk. – Thomas Owens Aug 20 '14 at 15:27
  • Here we're on a research project between several companies, so the process gets a little more complicated (as there is no actual customer). Still, having the document accepted by the client makes it a contract, and allows to check you have reached an understanding. How does the customer verify you have understood his needs if you don't provide him with your (functional) specification? – Pierre Arlaud Aug 20 '14 at 15:30
0

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.