The Software Concordance: A User Interface for Advanced Software Documents Satish Chandra Gupta Department of EECS University of Wisconsin-Milwaukee email: scgupta@cs.uwm.edu Tien N. Nguyen Department of EECS University of Wisconsin-Milwaukee email: tien@cs.uwm.edu Ethan V. Munson Department of EECS University of Wisconsin-Milwaukee email: munson@cs.uwm.edu ABSTRACT The Software Concordance is a hypermedia software de- velopment environment exploring how document technol- ogy and versioned hypermedia can improve software doc- ument management. The Software Concordance’s central tool is a document editor that integrates program analysis and hypermedia services for both source code and multi- media documentation in XML. The editor allows develop- ers to embed inline multimedia documentation, including images and audio clips, into their program sources and to bind them to any program fragment. Web style hyperlinks are also supported. The developers are able to move seam- lessly between source code and the documentation that de- scribes its motivation, design, correctness and use without disrupting the integrated program analysis services, which include lexing, parsing and type checking. This paper motivates the need for environments like the Software Concordance, describes the key features and architecture of its document editor and discusses future work to improve its functionality. KEY WORDS software engineering environments, versioned hypermedia 1 Introduction The software development life cycle consists of many phases: requirement analysis, high-level design, low-level design, development, testing, deployment, and mainte- nance. A software system primarily consists of source code and formal specifications created during the develop- ment phase. Other phases generate a variety of documents such as requirement specifications, design documents, test cases, bug reports, user manuals, and deployment and tran- sition procedures. These documents are used to develop the source code, test its correctness, and maintain it. Since they have implicit or explicit structure, they can be represented as structured documents. In a broader sense, source code is also a structured document that specifies a sequence of instructions to be ex- ecuted by a computer to perform a task. Similarly, other formal specifications are also structured documents. Struc- This research was supported by the U. S. Department of Defense and by NSF CAREER award CCR-9734102. tured documents can be divided into two categories [14]: formal and informal. Formal documents include program source code and formal specifications. Informal documents include all other documents. A formal document is writ- ten using a formal language, and formal languages have precisely defined semantics. Therefore formal documents can be understood and analyzed by tools such as compilers. An informal document is written using a natural language, which does not have precisely defined semantics. There- fore, the process of understanding informal documents can not be automated, and human intervention is required. Modern software systems are highly complex. A soft- ware engineer spends a significant amount of time reading and understanding informal documents in order to develop and maintain formal documents. In practice these two sets of documents are maintained separately. Informal docu- ments are usually rich in formatting, and are managed using a word processor such as Microsoft Word or FrameMaker. On the other hand, formal documents, usually stored as plain ASCII text, are maintained by a text editor. A typical scenario is that while performing a test case, a bug in a particular functionality is found, and a bug report is generated. In order to fix this bug, an engineer needs to read the bug report, test case and requirements specification in order to find the corresponding design document. Then, he analyzes the appropriate piece of source code, makes modifications, recompiles, and tests the system. Since in- formal and formal documents are maintained separately by different editors, the process has inefficiencies. These inefficiencies can be removed by using a struc- tured document editor, which unifies the navigation and editing of formal and informal documents and can use hy- permedia technology to maintain the relationships between these documents. Moreover, the power of multimedia can be exploited to enrich the documentation of the source code. As a program source editor, it should allow devel- opers to embed multimedia documentation and hyperlinks in their source code, while still supporting program analy- sis services such as lexing, parsing, and type checking. Such an editor requires a uniform document model for informal and formal documents. The model should support editing and program analysis services, and should allow ac- cess to any fragment of the document to create hyperlinks. In programming language tools, the Abstract Syn-