<?xml version="1.0" standalone="yes"?>
<Paper uid="A97-1037">
  <Title>Customizable Descriptions of Object-Oriented Models</Title>
  <Section position="2" start_page="0" end_page="0" type="metho">
    <SectionTitle>
1 Introduction: Object Models
</SectionTitle>
    <Paragraph position="0"> With the emergence of object-oriented technology and user-centered software engineering paradigms, the requirements analysis phase has changed in two important ways: it has become an iterative activity, and it has become more closely linked to the design phase of software engineering (Davis, 1993). A requirements analyst builds a formal object-oriented (OO) domain model. A user (domain expert) validates the domain model. The domain model undergoes subsequent evolution (modification or adjustment) by a (perhaps different) analyst. Finally, the domain model is passed to the designer (system analyst), who refines the model into a OO design model used as the basis for implementation. Thus, we can see that the OO models form the basis of many important flows of information in OO software engineering methodologies. How can this information best be communicated? It is widely believed that graphical representations are easy to learn and use, both for modeling and for communication among the engineers and domain experts who tqgether develop the OO domain model.</Paragraph>
    <Paragraph position="1"> This belief is reflected by the large number of graphical OO modeling tools currently in research labs and on the market. However, this belief is not accurate, as some recent empirical studies show. For example, Kim (1990) simulated a modeling task with experienced analysts and a validation task with sophisticated users not familiar with the particular graphical language. Both user groups showed semantic error rates between 25% and 70% for the separately scored areas of entities, attributes, and relations. Relations were particularly troublesome to both analysts and users. Petre (1995) compares diagrams with textual representations of nested conditional structures (which can be compared to OO modeling in the complexity of the &amp;quot;paths&amp;quot; through the system). She finds that &amp;quot;the intrinsic difficulty of the graphics mode was the strongest effect observed&amp;quot; (p.35). We therefore conclude that graphics, in order to assure maximum communicative efficiency, needs to be complemented by an alternate view of the data. We claim that the alternate view should be provided by an explanation tool that represents the data in the form of a fluent English text. This paper presents such a tool, the MODELEXPLAINER, or MODEx for short, and focuses on the customizability of the system.1 Automatically generating natural-language descriptions of software models and specifications is not a new idea. The first such system was Swartout's GIST Paraphraser (Swartout, 1982). More recent projects include the paraphraser in ARIES (Johnson et al., 1992); the GEMA data-flow diagram describer (Scott and de Souza, 1989); and Gulla's paraphraser for the PPP system (Gulla, 1993). MoDEx certainly belongs in the tradition of these specification paraphrasers, but the combination of features that we will describe in the next section (and in particular the customizability) is, to our knowledge, unique.</Paragraph>
  </Section>
  <Section position="3" start_page="0" end_page="253" type="metho">
    <SectionTitle>
2 Features of MoDEx
</SectionTitle>
    <Paragraph position="0"> MODEx was developed in conjunction with Andersen Consulting, a large systems consulting company, and the Software Engineering Laboratory at the Electronic Systems Division of Raytheon, a large Government contractor. Our design is based on initial interviews with software engineers working on a project at Raytheon, and was modified in response to feedback during iterative prototyping when these software engineers were using our system.</Paragraph>
    <Paragraph position="1"> * MoDEx output integrates tables, text generated automatically, and text entered freely by the user.</Paragraph>
    <Paragraph position="2"> Automatically generated text includes paragraphs describing the relations between classes, and paral(Lavoie et al., 1996) focuses on an earlier version of MoDEx which did not yet include customization.</Paragraph>
    <Paragraph position="3">  graphs describing examples. The human-anthored text can capture information not deducible from the model (such as high-level descriptions of purpose associated with the classes).</Paragraph>
    <Paragraph position="4">  * MoDEx lets the user customize the text plans at run-time, so that the text can reflect individual user or organizational preferences regarding the content and/or layout of the output.</Paragraph>
    <Paragraph position="5"> * MoDEx uses an interactive hypertext interface (based on standard HTML-based WWW technology) to allow users to browse through the model. * Input to MoDEx is based on the ODL standard developed by the Object Database Management Group  (Cattell, 1994). This allows for integration with most existing commercial off the shelf OO modeling tools. Some previous systems have paraphrased complex modeling languages that are not widely used outside the research community (GIST, PPP).</Paragraph>
    <Paragraph position="6"> * MODEX does not have access to knowledge about the domain of the OO model (beyond the OO model itself) and is therefore portable to new domains.</Paragraph>
  </Section>
  <Section position="4" start_page="253" end_page="254" type="metho">
    <SectionTitle>
3 A MoDEx Scenario
</SectionTitle>
    <Paragraph position="0"> Suppose that a university has hired a consulting company to build an information system for its administration. Figure 1 shows a sample object model for the university domain (adapted from (Cattell, 1994, p.56), using the notation for cardinality of Martin and Odell (1992)) that could be designed by a requirements analyst.</Paragraph>
    <Paragraph position="1">  Once the object model is specified, the analyst must validate her model with a university administrator (and maybe other university personnel, such as dataentry clerks); as domain expert, the university administrator may find semantic errors undetected by the analyst. However, he is unfamiliar with the &amp;quot;crow's foot&amp;quot; notation used in Figure 1. Instead, he uses MoDEx to generate fluent English descriptions of the model, which uses the domain terms from the model. Figure 2 shows an example of a description generated by MoDEx for the university model. Suppose that in browsing through the model  using the hypertext interface, the university administrator notices that the model allows a section to belong to zero courses, which is in fact not the case at his university. He points out the error to the analyst, who can change the model.</Paragraph>
    <Paragraph position="2"> Suppose now that the administrator finds the texts useful but insufficient. To change the content of the output texts, he can go to the Text Plan Configuration window for the text he has been looking at, shown in Figure 3. He can add to the text plan specification one or more constituents (paragraphs) from the list of pre-built constituents (shown in the lower right corner of Figure 3). After saving his modifications, he can return to browsing the model and obtain texts with his new specifications.</Paragraph>
    <Paragraph position="3">  A Section must be taught by exactly one Ptofee~ot and may belong to zero or more Cotuses. It must b e taken by one or more Stud~nt.~ and may have at most one TAD server which receives requests via a standard Web CGI interface and returns HTML-formatted documents which can be displayed by any standard Web browser. The documents generated by MoDEx are always generated dynamically in response to a request, and are composed of human-authored text, generated text and/or generated tables. The main requests are the following:</Paragraph>
    <Paragraph position="5"> sity administrator, the analyst needs to document it, including annotations about the purpose and rationale of classes and attributes. To document it, she configures an output text type whose content and structure is compatible with her company's standard for OO documentation. An example of a description obtained in modifying the text plan of Figure 3 is shown in Figure 4. (This description follows a format close to Andersen Consulting's standard for documentation.) This description is composed of different types of information: text generated automatically (section Relationships), text entered manually by the analyst because the information required is not retrievable from the CASE tool object model (section Purpose), and tables composed both of information generated automatically and information entered manually (section Attributes). The analyst then saves the text plan under a new name to use it subsequently for documentation purposes. Note that while the generated documentation is in hyper-text format and can be browsed interactively (as in the I-DOC system of Johnson and Erdem (1995)), it can of course also be printed for traditional paper-based documentation and/or exported to desktop publishing environments.</Paragraph>
  </Section>
  <Section position="5" start_page="254" end_page="255" type="metho">
    <SectionTitle>
4 How MODEX Works
</SectionTitle>
    <Paragraph position="0"> As mentioned above, MODEx has been developed as a WWW application; this gives the system a platform-independent hypertext interface. Figure 5 shows the MoDEx architecture. MoDEx runs as a  ument such as that shown in Figure 3 which allows a user to load/edit/save a text plan macro-structure specification. A representation corresponding to the text plan of Figure 3 is shown in Figure 6. Once edited, this representation can be stored permanently in the library of text plans and can be used to generate descriptions. In this representation, User Text indicates free text entered for a title, while Relations- Text and Examples-Short are schema names referring to two of the eight predefined text functions found in a C++ class library supplied with  * Object Model Loading. This loads an object model specification and generates a document displaying the list of classes found in the model.</Paragraph>
    <Paragraph position="1"> * Description Generation. This returns a description such as that shown in Figures 2 or 4. To generate a description, the text planner creates a text structure corresponding to the text plan configuration selected by the user. This text structure is a constituency tree where the internal nodes define the text organization, while the bottom nodes define its content. The text content can be specified as syntactic repre- null sentations, as table specification and/or as human-authored text for the titles and the object model annotations. The text structure is transformed by the sentence planner which can aggregate the syntactic representations (cf. conjunctions and in description on Figure 2) or introduce cue words between constituents (cf. expression For example on Figure 2). The resulting text structure is then passed to the text realizer which uses REALPRO (Lavoie and Rambow, 1997), a sentence realizer, to realize each individual syntactic representation in the text structure. Finally, a formatter takes the final text structure to produce an HTML document.</Paragraph>
    <Paragraph position="2"> * Object Model Annotation Editing. This allows the user to edit human-authored annotations of the object model. This editing can be done via links labelled Edit ... which appear in Figure 4. These human-authored texts are used by some of the pre-defined text functions to generate the descriptions.</Paragraph>
  </Section>
class="xml-element"></Paper>