peer reviews · requirements

Passive voice requirements – A pain in your Buttocks!?

Why ”passive voice” requirements actually can become a night mare?

If you are like me and like clear and precise requirements with as much clear meaning as possible you might try to wash out some bad language in your requirements. Perhaps you review a set of IT system requirements on the highest level and find a requirement written like this:

“All critical errors shall be logged”.

You might continue and think; “That’s a bit vague but I guess that the reader of the requirement understands this, and the requirement is under a specific section of the set named System management, so is should be fine. I need to discuss with the author on what a critical error is, and we need to investigate how to verify that these errors defined as critical get logged”.

But you might also be a nerd like me and immediately say that “no, we must not have any passive voice requirements in our set of requirements, period!”. Its also in violation of the INCOSE guide in writing requirements, i.e. Rule R2 – Use active voice. But the author of the requirement is much likely not aware of that guide or quality rule in the first place..

Ok, fine. But what does this mean and why is this so dangerous to allow passive voice requirements?

Does it really matter if I write a passive voice requirement? I understand it and this should everyone else also do. Besides, it’s a short high level system requirement and we will get back to the verification details later. These details will come when I start to specify the subordinate level of requirements derived from this one or when I prepare a design solution which will take care of the requirement.

INCOSE says in the rule R2 mentioned above that “requirements not stating the subject must be avoided”. Whats that? I have written that “errors shall be logged”. The word Error is my subject, right?

No, its not actually. When looking into the example sentence in more depth its quite clear that it lacks a SUBJECT. The sentence does not explain WHO will actually log the errors that the writer of the requirement see must be logged. Let’s look at this figure:

From this figure its quite easy to understand that the solution for a passive voice requirement can both be a system function of some sort or a service provided by someone outside of the system.

Same applies to ALL types of passive voice requirements:

Lights shall be integrated in the dashboard… OK. Fair enough, but it this a requirement saying that we require someone to integrate the lights or is the purpose something else?

Perhaps the lights are supposed to be hidden (integrated) in the dashboard and the requirement is trying to capture this?!

The ONLY solution if you ever encounter requirements written in passive voice (and you will) is to go back to the author (or the stakeholder with the need) and ask what’s the purpose of the requirement in question. Ask WHY do you want to integrate these lights? Or WHY do you have to log critical errors?

The answer to these questions will help you to rewrite the requirement so it captures the intention and purpose behind its existence. Because if you don’t do this you will live with the impression that everything is fine, and the development is on its way towards a solution that will fulfil your requirement. The problem(s) will emerge with the first prototype or even worse during verification of the system towards the requirement. Then its LATE in the process and you will have to manage the probable delay or the added cost of doing a late design change.

So, PLEASE don’t ever write OR accept requirements written in passive voice. You have no idea what the result will be, and it will for sure at one point in time pop up and bite you in your butt!

One of the solutions can be to use requirement patterns, butt (hehe) more on that another time….

NLP · Uncategorized

The perception of quality – a double-edged sword?

quality

It was a while, but now I am back with a short blog on the subject of QUALITY.

I accidently heard two persons at a train station arguing if the ticket service delivered by a ticked machine was of good quality. There where different opinions depending on if you where the buyer or the employee helping out..

What is quality and how does one get it?

Quality is an often misused word. You can hear “the quality was bad” or “supplier has no sense of quality”.

I personally do not think that a majority of cases actually are caused by a DELIBERATE action to deliver something bad or to behave in a bad way, so what is it all about?

If I had to define the meaning of the word quality, it would be something like this:

Quality is the totality of features and characteristics of a system or service that bears its ability to satisfy stated or implied needs.

So what am I saying here?

If I want to get something from someone and ask for “good quality” I better be precise in describing what that is, do you agree? Some reflections:

  • How do one know that I get ALL those features and characteristics if I don’t express them in a Correct way and how can I explain them in a Consistent way, so they don’t contradict each other? Very often characteristics can stay on collision course… A product can be user friendly, but perhaps not that secure? Or withstand mechanical force, but not being light weight and cheap?
  • And if I shall give you something that fulfils both stated and implied needs, does that mean that I need to be able to read your mind?

No, of cause not, but the next time you argue that the quality is bad, are you sure it’s the other parties fault all together?

The answer is seldom black or white and I want to argue that a good product in one scenario might be a catastrophe in another. It depends…

The answer is to do some proper systems engineering (at least if you work with complex products or services). But, really, anyone would benefit in thinking on the context, the need, the use case(s) and the end goal required.

Try to put boundaries of your problem space and try to express these needs using correct grammar, a defined consistent vocabulary and try for good sake to avoid contradictions that inevitable will increase the possibility for misunderstanding, confusion and errors.

The hardest part is to be complete in your expression of your need. You can not rely on the recipient being able to read your mind. You have to have the receiver of the information in mind!

A high degree of understanding is dependent on semantics, syntax and something language specialists call pragmatism, or how to use the appropriate language dependent on the context. So, its VERY much up to you as the receiver to send the right signals using a proper way of communication.

confused-woman

I want to end by changing an old phrase:

“You get what you ask for”, to:

“you get what the receiver THINK you ask for”.

That’s a huge difference and perhaps the next time you argue on the lack of quality, you should stop and think on your own role in the game…

PS. The customer at the train station was right. The machine SHOULD give you a ticket when you payed for it and the excuse that “it seems to be broken”, did not solve anything in this case.

To be continued

Next time I think I will continue to discuss language and understanding. Its a fascinating subject!