Guest Post by

Exchanging requirements correctly

Imagine you ordered a system component from one of your suppliers. You would write out a requirements specification and slap it on his desk. In a perfect world the supplier would know exactly what you need and three months later you would get a perfect system component according to your specifications. If only it were that simple.

In practice there are two important differences: First of all you have to ask for feedback from your supplier before he gets started. Second of all there will probably be some back-and-forth, resulting in change requests on both sides. If you ignore these aspects then the development can take a nasty turn. Both sides bear a lot of risk: The contractor could receive an unsatisfactory result that may still technically conform to the contract. The supplier, on the other hand, risks having to shoulder big contractual penalties if important requirements changes get lost or if important requirements simply get forgotten.

How should one deal with these problems? This article will look at two aspects: the process level (how to deal with changes); and the technical level (how to ensure a technically efficient exchange of requirements)?

Technical aspects

Let’s begin with the technical aspects. Luckily it is no longer necessary to export requirements as Word, Excel or PDF documents. With the ReqIF (Requirements Interchange Format) ¹there is an open, standardized format that can be transferred without loss. Most people will know why MS office, PDFs or similar formats are not suitable for exchanging requirements. But because they are important for the present discussion a brief summary can be found below:

Requirements need to be clearly partitioned. This might work out in Excel: one line in Excel corresponds to a requirement. With Word things becomes more difficult as it is harder to make this partition more explicit, and with the PDF format this is only possible using imprecise heuristics.

Requirements should continue to be identifiable, that is, they need to have an ID. In Excel this is achievable if you save the ID in its own column. There is no elegant solution to this problem in other formats there.

Changes should also have attributes such as priorities, comments, statuses etc. In Excel this can take place in additional columns, but in Word and PDFs there is no satisfactory solution.

And finally, requirements need to be able to be connected with each other. Requirements specifications should be linked in such a way that it is clear which system requirement will be executing which client requirement. Here too there are no usable solutions for the formats mentioned.

Excel is the strongest contender in this list. It is however restricted in that it doesn’t allow images to be cleanly embedded. And that is often needed.

At this point it should be made clear that we are not just talking about the exchange or requirements. Internally a professional solution is (hopefully) being used for the requirements management. But if the partners do not have the same tools then an export must be carried out. In the past that has ended up being in the formats mentioned above.

ReqIF for exchanging requirements without loss

Fortunately we have the ReqIF format. It allows for the exchange between requirements without losses. ReqIF stands for “Requirements Interchange Format”. It was explicitly developed for the exchange between requirements and has none of the weaknesses mentioned above. What is much more important in practice is that all serious requirements management tools today supports ReqIF.

ReqIF is an international standard. The object Management Group (OMG) – you may know it as standardization in UML – is also responsible for ReqIF. But even a sharply defined standard like ReqIF needs to be implemented properly. That’s why a working group has existed for many years that has attracted many ReqIF users and producers of ReqIF tools.² It is supported by an open source reference implementation by ReqIF which provides orientation for tool producers.³

The result is a robust technical foundation for the exchange of requirements that can be used to execute exchange processes. The development of ReqIF has also shaken the tool market up quite a bit. The costs of migrating one tool to another have decreased due to the open, loss-free format for requirements. Many new tool creators have also appeared on the market.

Getting cooperation as simply as possible

Getting cooperation as simply as possible

Process aspects

Unfortunately transferring the data is only half the story. The problem, as is so often the case, is with the changes and the feedback. That is to say, your partner’s feedback needs to be integrated into your own database while at the same time paying attention to continual development and versioning. Let’s look at a concrete example:

Imagine the contractor sends a requirement to the supplier who returns it with the status marked as “accepted”. In the meantime the contractor may have expanded the requirements. Note: it is important that the expanded elements are not also marked as “accepted”. Similar caution is called for when the requirement specifications are connected: a change in one should lead to a reassessment of requirements in the other.

Preparation in the HIS process

There’s no need to keep reinventing the wheel. Processes can continue to be used. And luckily we have a useful template for exchanging processes. The producer initiative software (HIS) is a working group in the auto industry that has put in a lot of preparation work. The result is the so-called HIS process.4

The HIS process covers all important aspects for the successful requirements exchange. The “what” is often more important than the “how”. It requires e.g. that the parties agree on an exchange format without prescribing one. It is interesting that ReqIF was explicitly developed to make the HIS process possible. This all makes the ReqIF a good choice for the execution.

The process is divided into six use cases. In practice this should be seen as a starting point and it should be adapted and expanded according to the organization’s requirements. The six use cases are:

  • Initialization – that is the discussion phase among partners with reference to technical and logistical details.
  • Exporting and packaging – For the exchange the “right” requirements need to be exported and processed.
  • Transfer- three companies are very different in this regard: For one of them email attachments are perfectly acceptable, others require the data needs to be encrypted and digitally signed.
  • Import – beside the pure import you may also need to carry out a plausibility evaluation.
  • Evaluation of requirements – The objective is to evaluate requirements in any number of forms.
  • Assessing the evaluation – The results of the evaluation are then returned with the help of above-mentioned use cases. They need to be assessed there again.

Evaluating requirements

In some companies there are dozens of slightly different status attributes. That’s why the status attributes of the HIS process need to be used if internal company policies don’t contradict that.

The image on the left shows the status and transitions for suppliers, on the right you see statuses and transitions for producers

The image on the left shows the status and transitions for suppliers, on the right you see statuses and transitions for producers

Beyond the status there is also a commentary attribute that sheds light on a particular status.

Attribution or open points?

And finally there is the question about what needs to be transferred. The suggested approach is to issue requirements with a status and commentary attributes that can be filled by your partner. There is another approach though. A list of open points can also be transferred. That makes sense particularly if the number of requirements is high and the number of problematic requirements is low. Unsurprisingly this approach comes from the auto industry. After all that is an industry in which tens of thousands of requirements specifications are normal. Ideally a list with requirements would be linked in its traceability. The transfer technology needs to support that as well.

Living the requirements exchange

An exchange process can be very simple, but it can also be complicated. The old adage rings true: “Keep things as simple as possible and as complicated as necessary.” A process needs to be lived in order for it to add value. And the simpler it is, the higher the chances are that it will be successful.

If it is lived properly then all partners can be sure that everyone will be able to read and understand the requirements. If another pragmatic traceability option exists then developers will come across changed requirements given that the tool being used will have marked derived aspects as being “suspicious”.

A structured exchange of requirements is not easy to live. But the introduction of ReqIF has made it a little easier. If it is lived properly, the value could be enormous.

 

Literature

[1] Requirements Interchange Format: http://re-magazine.ireb.org/issues/2014-3-gaining-height/open-up
[2] ProSTEP ReqIF Implementor Forum: http://www.prostep.org/en/projects/internationalization-of-the-requirements-interchange-format-intrif.html
[3] ReqIF Sudio – a RE tool based on the open source eclipse requirements modeling framework: http://formalmind.com/de/tools/studio/
[4] The HIS process for the exchange of requirements: http://formalmind.com/blog/his-exchange-process-requirements-all-you-ever-wanted-know/

Dr Michael Jastram is a systems engineer who specializes in requirements modelling. He is the founder and project lead in Eclipse Requirements Modeling Frameworks, an open source project that seeks to implement ReqIF in requirements modelling approaches. As an advocate for openness he shares his knowledge in books, articles, speeches and events as well as in his weekly blog entitled System Engineering Trends (German) and Formal Mind Blog (English). Mr Jastram has been in the business for 20 years, ten of which he has spent in the USA where he obtained his degree in software engineering and architecture from M.I.T. He has also worked in several start-ups and has founded the Düsseldorf Java user group called rheinjug e.V. At present he is serving as CEO of the Formal Mind GmbH and running the ReqIF.academy, an online library that facilitates the exchange of requirements.

Tags:
0 replies

This discussion is missing your voice.

Leave a Reply

Your email address will not be published. Required fields are marked *