Requirements Engineering is Document Engineering!

The claim that requirements engineering ultimately is document engineering, is neither new nor original [Webster]. Nor is it entirely true. Personally, to be frank, I would feel uncomfortable when for example formal methods would be dismissed in favor of hypertextual support only. Nevertheless, managing the documents involved in software engineering certainly is a problem. So, taking this claim as a starting point, what criteria do we wish our documentation to satisfy?

Requirements Engineering is Document Engineering!

online -- change management
distributed -- multi-user
hypertextual -- severely intertwinkled
multimedia -- from a variety of conceptual domains

slide: Requirements Engineering is Document Engineering!

First of all, nowadays, we want our documentation online, to be viewable with our favorite browser, and we like changes to be reflected immediately.

Secondly, very likely we will cooperate with other people, so our documentation will be scattered around (possibly the globe), and we need support to manage a distributed document base.

In the third place, our requirements and software documentation, let alone maintenance fixes and updates, will be heavily interrelated and full with cross-references. Evidently, hypertextual support, in the form of links, augmented with indexes, is simply a necessity.

Finally, both requirements specification and system design and implementation may profit from the use of multimedia, for example in the form of video field studies in the first case or animations in the latter case.

Not mentioned, but probably equally important, is some standard for the exchange of information and documentation. In our experiment we have used (pure) SGML as a basis. It is worth mentioning that at the time we provided full support for this format, including online browsing, printing and multimedia (applet) support [Animate].

In the sections that follow, I will discuss my experience with documenting a fairly large software system, in order to establish the potential difficulties that arise when actually attempting to realize the documentation support for which the requirements were specified above.