Practical Software Engineering

Requirements Tracking through the Web

Using the Web for Requirements Tracking

The World Wide Web supports the sharing of structured multimedia documents with links to one another and to other material, not necessarily in HTML format. This makes it a suitable base technology on which to develop a requirements tracking system for software engineering that tracks the relationship between requirements, analysis, design, implementation, application and maintenance.

There are complex requirements tracking tools being developed that use the full client-server capabilities of the web to provide highly integrated systems. For CPSC451 we will use the web more simply to develop a set of linked documents tracking the customer group requirements specification, the negotiation with the supplier group to clarify them, the design specification, the customer commentary on this, the implementation, acceptance procedures, and so on.

Rather than use special-purpose servers we will take advantage of the web's capability to link documents held in different locations, and generate a sequence of documents held in the directories of those in the customer and supplier groups. A single master index managed by someone in one of these groups will be used to make the distributed set of documents available to everyone in the groups.

Setting up a Web Directory in Your Home Directory

The Computer Science Department Web server provides web access to files in a directory named www in your home account. If you do not have such a directory yet you can create one by logging into your CPSC account and typing:-

  mkdir www

This needs to be read-accesible by others and, dependent on the defaults for your account, you may also need to change the permissions to give read access:-

  chmod 755 www

Since you may have other courses that involve use of your www directory, it is a good idea to put all your CPSC451 material in its own directory:-

  cd www
  mkdir 451
  chmod 755 451

Any file that has general read permission that you put in your www directory or its sub-directories will now be served to anyone requesting it from a web browser such as Netscape. The url (uniform resource locator) for accessing a file called, for example, spec.html in your /www/451 directory would be:-

  http://www.cpsc.ucalgary.ca/~loginname/451/spec.html

where loginname is your login name (which is also the name of your home directory). Note that the sub-directory www is not mentioned in the url.

Linking and Annotating Material

By putting all the customer and supplier documentation in the /www/451 directories of members of the customer and supplier teams it automatically becomes available to everyone. However, it is not linked together and it may not be obvious how the documents relate to one another. Two things can be done to improve the situation.

First, someone in the customer group should agree to become documentation manager for the entire project and maintain an index in their /www/451 directory of all the documentation from both customers and suppliers. Please let your TA know the URL of this index as soon as possible, so that the TA can see to it that it gets indexed into the course notes. This index will contain pointers to the distributed set of documents allowing them all to be accessed from one place. Anyone needing to look at the project documents will start with the index and click on a document in it to fetch that document. Anyone generating a new document that should be entered in the index should email its url to the documentation manager specifying where it belongs in the index.

Second, while you cannot edit a document in someone else's account, you can fetch it with a web browser, save its source, annotate that source with your comments, and make the annotated document available in your account. Thus, the index will grow to be a sequence or a tree of documents such as a customer specification, a version annotated by the suppliers with queries about the specification, a version of this annotated by the customers with answers to queries, and so on. Similarly, an initial design specification from the suppliers can be annotated by customers.

Style of Annotation in HTML

You will need to establish some style guidelines for documents so that you can distinguish annotations from the original. One good technique is to use a horizontal rule before and after annotation. Tags for bold and italic can be used to mark particular sections of text to which you are making reference. There is no obvious or standard way of doing this. Experiment with HTML and decide on an approach for your group (but don't spend more time on an annotation scheme than you do on the actual software engineering project!).

The use of color is good, but DO NOT rely on color alone, since some people may be viewing your documents on a monochrome monitor (like the instructor, for instance). And don't overdo it.

What Should be Documented on the Web

Any documents that you can generate on paper you can also put up on the web, so that your project web should finally provide a complete account of all the activities of the project. For example, you can link to design material that includes screen-dumps as GIF images. In a real-world project that used the web itself to implement a client-server system you would even be able to link to the working system so that the requirements and design information was available for maintenance and enhancement support. If your implementation is on the departmental unix system then you should be able to provide a link that starts a live demonstration.

Practical Software Engineering, Department of Computer Science

Rob Kremer