Requirements Quality

Why use Word for Requirements Documentation?

... you might ask. Usually, I strongly encourage our customers to use suitable tools for managing their requirements. There are plenty of reasons why I recommend using professional tools for requirements management, but an important reason is to ensure requirements traceability. For example, of the six sources of RE project failures identified by Michelle Boucher, at least three have to do with traceability. While we do recommend other tools, Word is available in most companies, documents are easy to exchange, the review mode is pretty good and sometimes using other tools is simply not an option for different reasons. Hence, many people do use Word to create requirements documents. My own experience in using Word for authoring a requirements document is that it seems to work well in the beginning, but as soon as already documented requirements begin to change things start to get nasty. Especially if there is not just one requirements document, but several.

Ok, after I publish this blog post, I will probably get some angry calls from my sales department... Well, truth must be told. There are many crazy defects in requirements, and, as I wrote in my last post, you can detect quite a bunch of them automatically (and you should do so!). When I present our automatic methods for natural language requirement smells or automatic methods for detecting defects in tests to our customers, I'm proud to say that they are usually very excited. Sometimes they are too excited and then this can turn into a problem. What I mean is that I explain all the amazing things that you can detect with tools and suddenly people think that the tool will solve all the problems that they face. Spoiler alert: It doesn't. And because we're a company that is interested in happy customers, I want to briefly summarize all the problems (*that come into my mind) that a tool can't solve. And because I don't want to leave you in despair, I will also suggest some solutions, how I personally would suggest to work on that problem.

I am a strong advertiser of modern, automatic methods to improve our day to day life. And so I really don't want to check by hand whether my tests and requirements fit my template, or whether my sentences are readable. So quality assurance and defect detection, for example reviews or inspections, should use automation as far as possible. BUT: When I speak to clients, sometimes people get so hooked up by the idea of automatic smell detection, that I need to slow them down. Therefore, this post tries to give a rough overview: What is possible to detect automatically? The answer basically depends on two questions:

  1. How much syntax (or structure) do your artifacts and tests have?
  2. Which language do you use?
In this post I will refer to requirements artifacts here and there, but the answers are pretty much the same for both system tests and requirements.