A norm for requirements in BMPS

As a requirements engineer I’ve often wondered myself about the balance between the effort put into creating specifications versus the actual usage of it. Off course development teams need some information to start working on, but the further you get in a project, the more the team knows what is going on and the less value your specifications have. Isn’t it so that specifications devalue even more when the system goes into a maintenance phase? Use cases which are very useful to develop the system are actually not so handy for maintenance as focus shifts from a development team wanting to know how the user interacts with the systems, to a maintenance team wanting to know where a certain form or business rule is used in order to make a change or an impact analysis. Keeping the specification a valuable and up-to-date asset takes a huge effort with unknown outcome...

I suppose anyone working in software development will confirm that software documentation often suffers from one or more problems below:

• it is nonexistent or is of poor quality;
• it is outdated;
• it may be over abundant on some aspects without a definite objective;
• it may be difficult to access when the are scattered on several location and in different formats;
• it doesn’t always get the interest from the programmers that it needs;
• it is difficult to standardize, due, for example, to project specifics.

The results of this, is that maintenance teams only trust the actual realized software system, the source code and the database tables itself. In traditional software development the source code however is hard to read. In those situations documentation is needed to explain how things work together and how requirements are implemented in the system. These descriptions however suffer from the problems listed above.

The outcome of a survey held amongst several maintenance personnel won’t surprise you, it gives an idea about what documentation artifacts are most valued by maintenance personnel probably due to the problems above:




This survey also showes that software code and comments are mostly valued by maintenance teams!

Knowing what causes the problems with documentation can help us decide on how to document in the future and what to look for in tooling to support that process.

Working in the field of BPM, I’ve found that BPM Suites offer great functionality to overcome several problems with software documentation. What the BPM suites offer in this field is based around the following four features:

1. The first good thing about BPM suites is that the models created by BPM engineers in the suite are well readable by maintenance personnel. The models are directly executable so there is no software coding needed to translate the models into the code to create an executable. The fact that documentation lacks interest of programmers becomes less relevant since the models they create are often well readable.

2. The second good thing is that these models correlate with assets we are used to specify, like a domain model, user interfaces and a process model. There is no need to create a written specification of these artifacts discussions on how to document belong to the past.

3. The next good thing is that most BPM suites keep traces between implementation artifacts of different types. This makes it possible for instance to find out in which process steps a certain business rule is used.

4. The fourth good thing about BPM suites is that requirements information is stored in the system close to the implementation artifacts helping with the access and standardization of requirements.

For a client I currently work for I’ve developed a documentation norm specifying in detail what to document in text and what to document in the suite (in this case Aquima). To get a good idea on what and how to document, I’ve started from the models often available in the suites. These models I linked to the requirements artifacts of the Rational Unified Process (RUP). Linking to RUP makes it easier for external auditors to assess the quality and completeness of the available documentation.

Please contact me for more information on the norm...