abstract

In this position paper for HTF4 we will look at an example of applying hypertext technology to support the maintenance of documents in the software engineering life-cycle. Reflecting on this example, we will discuss the requirements full hypermedia support for software engineering must satisfy. After that, we will look at some pragmatical issues that arise when one attempts to document software and its requirements in a hypertextual fashion on a large scale, including text processing, indexing and graphical facilities for reverse engineering.

The full version of this paper can be found at http://www.cs.vu.nl/~eliens/online/papers/htf4

Introduction

Put radically, software engineering is requirements engineering, and as a consequence, in the average project considerable effort is put in managing the documents that are delivered as milestones, documentation or reports, coming from analysts, system developers, steering committees, and what more.

Software Engineering is Requirements Engineering!

Toy example: examples/hush/coffee

slide: Software Engineering is Requirements Engineering!
Each of the phases in the software engineering life-cycle is characterized by its own collection of documents. For example for the analysis phase, the IEEE advocates the use of its ANSI/IEEE 830 standard to specify the requirements a system must meet. Such documents accumulate over the subsequent phases and during maintenance, in particular, retrieval becomes a problem, unless adequate document management support is offered. Another problem is that the original meaning of specifications may get lost or, worse, that specifications may become outdated, making (diagrammatic) reverse engineering support desirable.

As an experiment, we augmented the standard documentation format for our Software Engineering course with hypertextual support, that is (among others) links, allowing students to jump from documentation to code, and back. To be clear, students had to write the documentation and code themselves! In the following, I will discuss the issues that are involved in providing hypertextual support for requirements engineering and software documentation. But first of all let's look at the requirements such documentation must meet.

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.

DejaVU Online - The hush Documents

For a number of years, we have used hush in our Software Engineering course and we were confronted with the need to keep our documentation up to date. Naturally, we provided online help including references to external sources of information.

But often students also wanted to be able to look at the sources, and not only include files, as well. It is interesting to note here that most vendors of C++ class libraries we one day or another forced to give their source code away, simply because it appeared to be too difficult to understand the nature of their frameworks in any other way.

DejaVU Online -- The hush Documents

slide: DejaVU Online - The hush Documents
 Our inability to document software in an adequate way is an amusing problem in itself. It's solution may lie in the adoption of proper development methods and possibly in finding more intuitive means of clarifying the (conceptual) relations between the components of the system. An unsolved problem, in this stage, let me haste to add!

The Hush Online Technology Toolkit

Even with the existence of numerous tools for software documentation a number of issues come up when one attempts to arrive at a fully documented system.

First of all there are several kinds of document types, plain or structured text such as for example requirements specifications, but also code, in a bewildering variety, and configuration information.

Secondly, one needs s preferably uniform style of annotation for the various kinds of program code and configuration code.

Issues

  • document types -- code, configuration, text
  • annotation -- C++, Java, IDL, scripts
  • documentation format -- dot-tee pseudo SGML
  • tools -- Java/C++/IDL Doc
  • conceptual graphs -- ciao, acasia , dotty
  • indexing -- file level (find), content level (glimpse)
slide: The Hush Online Technology Toolkit
 For presenting the documentation, furthermore, one needs some suitable formatting language, such as HTML, LaTeX, or SGML. For hush I used the dot-tee format, which is somewhere in between SGML and HTML. An euphemism, indeed.

The formatting language must be (conforming to) the output of the various tools that are in use. In reality, I had to modify these tools to make them conform to my standard!

Text being text, it is nice, in addition, to be able to create conceptual graphs, preferably in a reverse engineering fashion.

And finally, a point which also holds for the previous issue, given the size of the potential document base, there must be support for indexing, both on a file level as well as on a content level.

Tools

The actual toolkit consists of a small collection of filters and scripts that may be used to generate HTML documents.

Tools

slide: Tools
 In addition, I used several utilities such as Acacia and  [Ciao] for creating graphs, Doc++ for creating structured documentation for C++ and Java and IDLDoc for documenting CORBA IDL. Minor modifications of these utilities were necessary though, in order to arrive at a consistent format.

Experiences

The result (eternally in construction) of this effort may be looked at at www.cs.vu.nl/~eliens/online/hush Clearly, as I will indicate in the conclusions, my initial goals have not all been realized. As concerns the effort involved, apart from the actual annotation, which is minimal due to the use of the aforementioned tools, creating documentation takes a lot of time. Not only in terms of CPU time, but also to see whether the documentation is right, or better adequate in relation to the investment of effort.

You need patience -- on a Sparc Ultra 167 (64MB)

  • 70 MB of documentation -- more than 3 * source
  • processing time -- over 5 hours
  • 'brute force reverse engineering' -- uniformly
  • localisation -- the bar takes time
  • virtual links -- where do I place the source
slide: Experiences
 As concerns the result, brute force reverse engineering turns our to be somehat insatisfactory. or an art I'll have to learn.

The localization of documents, that is the indication of their position in the source tree seems to be useful as a point of reference. But creating the bar, including the indexes to the various kinds of (code) documentation takes time.

As a programmer, one cannot wait for it (that is the documentation tools) to finish. More generally speaking, there is clearly a clash of perspectives here. The organisation of the code from the perspective of the programmer may radically differ from the organisation which is most desirable from the perspective of documentation!

Some leverage for this problem can be provided by wiring in support for 'virtual links' in the filters themselves. But still, the clash is there. An optimal solution is hard to find.

Conclusions -- additional requirements

In my opinion, software and requirement documentation support is important. In my experience, the documentation perspective must be accepted before documentation support is of any use. In practice, the documentation perspective may be experienced as annoying, as irrelevant, or simply orthogonal (meaning something completely different). So, before attempting to formulate additional requirements, we must convince ourselves that hypertextual access to our requirements and software documentation is important.

Additional requirements

  • animated demos -- plugins are platform dependent
  • interactive explanation -- to 'learn' the code
  • and probably more ...
slide: This is only the beginning ...
 Let me assure you, I do consider it as important, and reflecting on the need to provide adequate documentation, I only have to remember the occasions where I wished there was an animated demo running on my platform, or some kind of interactive explanation (as people may provide), or ...

Concluding, with the Web we have the opportunity to meet many of the requirements of software documentation as mentioned in the beginning almost for free. All we need is a little imagination to make it work as it should.

References

Principles of Object-Oriented Software Development, Technology, Tools and Applications, Computer Networks and ISDN systems, Vol 27. No 6, Elsevier, 1995, pp. 1105-1110 www.igd.fhg.de/www/www95/proceedings/papers/48/main.html - an SGML-based approach Bradford, 17-18 April 1996, Britisch Computer Society