Customizable Descriptions of Object-Oriented Models 
Benoit Lavoie 
CoGenTex, Inc. 
840 Hanshaw Road 
Ithaca, NY 14850, USA 
benoitOcogentex, com 
Owen Rambow 
CoGenTex, Inc. 
840 Hanshaw Road 
Ithaca, NY 14850, USA 
owen~cogentex, com 
Ehud Reiter 
Department of Computer Science 
University of Aberdeen 
Aberdeen AB9 2UE, Scotland 
ereiter~csd, abdn. ac. uk 
1 Introduction: Object Models 
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 re- 
quirements analyst builds a formal object-oriented 
(OO) domain model. A user (domain expert) vali- 
dates the domain model. The domain model under- 
goes subsequent evolution (modification or adjust- 
ment) by a (perhaps different) analyst. Finally, the 
domain model is passed to the designer (system ana- 
lyst), 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 im- 
portant flows of information in OO software engi- 
neering 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 ex- 
perts who tqgether develop the OO domain model. 
This belief is reflected by the large number of graph- 
ical OO modeling tools currently in research labs 
and on the market. However, this belief is not accu- 
rate, as some recent empirical studies show. For ex- 
ample, Kim (1990) simulated a modeling task with 
experienced analysts and a validation task with so- 
phisticated users not familiar with the particular 
graphical language. Both user groups showed se- 
mantic 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 con- 
ditional structures (which can be compared to OO 
modeling in the complexity of the "paths" through 
the system). She finds that "the intrinsic difficulty of 
the graphics mode was the strongest effect observed" 
(p.35). We therefore conclude that graphics, in or- 
der 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 customiz- 
ability of the system.1 
Automatically generating natural-language descrip- 
tions 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 para- 
phrasers, but the combination of features that we 
will describe in the next section (and in particular 
the customizability) is, to our knowledge, unique. 
2 Features of MoDEx 
MODEx was developed in conjunction with Ander- 
sen 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 ini- 
tial 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. 
• MoDEx output integrates tables, text generated 
automatically, and text entered freely by the user. 
Automatically generated text includes paragraphs 
describing the relations between classes, and para- 
l(Lavoie et al., 1996) focuses on an earlier version of 
MoDEx which did not yet include customization. 
253 
graphs describing examples. The human-anthored 
text can capture information not deducible from the 
model (such as high-level descriptions of purpose as- 
sociated with the classes). 
• 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. 
• MoDEx uses an interactive hypertext interface 
(based on standard HTML-based WWW technol- 
ogy) to allow users to browse through the model. 
• Input to MoDEx is based on the ODL standard de- 
veloped by the Object Database Management Group 
(Cattell, 1994). This allows for integration with 
most existing commercial off the shelf OO model- 
ing tools. Some previous systems have paraphrased 
complex modeling languages that are not widely 
used outside the research community (GIST, PPP). 
• 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. 
3 A MoDEx Scenario 
Suppose that a university has hired a consulting 
company to build an information system for its ad- 
ministration. 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. 
Figure 1: The University OoO Diagram 
Once the object model is specified, the analyst must 
validate her model with a university administrator 
(and maybe other university personnel, such as data- 
entry clerks); as domain expert, the university ad- 
ministrator may find semantic errors undetected by 
the analyst. However, he is unfamiliar with the 
"crow's foot" notation used in Figure 1. Instead, 
he uses MoDEx to generate fluent English descrip- 
tions 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 
254 
using the hypertext interface, the university admin- 
istrator 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 an- 
alyst, who can change the model. 
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 Configu- 
ration window for the text he has been looking at, 
shown in Figure 3. He can add to the text plan spec- 
ification one or more constituents (paragraphs) from 
the list of pre-built constituents (shown in the lower 
right corner of Figure 3). After saving his modifi- 
cations, he can return to browsing the model and 
obtain texts with his new specifications. 
File Edit View Go Bookmarks Options 
Directory ~indow Help 
[List of Classes] [List of Models] [Reload Models] 
[Configuration] ~ [About ModeIF.xolame,] 
Description of the Class" Section' 
General Observations: 
A Section must be taught by exactly one F$ofesso, and 
may ~clong to zezo oz more Cqu~e s. It must be tak¢o 
by one ca more Students and may have at most one 
TA. 
Examples: 
For example, Sectl is a Section and is taught by the 
professor Jolm Brown. It belongs to two Courses, 
Math165 and Math201, and is take~ by two Students. 
Frank Belfo~d and Sue Jones. It has the TA Sally Blake. 
Figure 2: Description Used for Validation 
........... ,-.,m~ ................. = .................... I;|? 
i[Jlc Edll ~ew Go Bookmarks ~Jans Dlr©c~r/ ~qndow 
Help 
Text Plsm Conflgm'aflon 
Tat Plmv V -'~'4'~"-(2~ ¢ 
..,:L ~..cr=,.on o= ¢= ¢.=. ,c~s ] 
0 z~.~ ~.: ~===~==) 
i --=- ~'~ ~omponent 
I . -- [ ~ose 
~butes 
3peretions 
:telafions-Teble 
:~elQ~ons-Te)d 
-:xemples-Long 
:xemples-Shod 
~~ ~ ~'~ " Rle-Reference 
Figure 3: Text Plan Configuration Interface 
Once the model has been validated by the univer- 
File Edit View Go Bookmarks Options 
Directory Window _Help 
[List of Classes] [List of Model.~] [Reload Models] 
[Co:ffi~otation] [H~ [About ModelEx~01amer] [Q3_~] 
~==:==~=È~=~È=ÈÈÈ~==::~==~==~:~:~====~==È=~::::::::::::::::::::::::::::~=~====~ 
Business Class: "Section' 
Purpose/Role: 
Course unit a student can take. 
Ed11. Pu~o.~e 
Attributes: 
ii Am~u~ JiDeser~ t~n . iiTY~e .................. i 
i i ...................................... n~ber iSecUo n T'--"T""'7""" identifier ~#1NTF~3 ~ ................. ]~'~ 
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 
Edit Attdbutee 
Relationships: 
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 docu- 
ments which can be displayed by any standard Web 
browser. The documents generated by MoDEx are 
always generated dynamically in response to a re- 
quest, and are composed of human-authored text, 
generated text and/or generated tables. The main 
requests are the following: 
ModEx 
m 
Request 
i 
Figure 4: Description Used for Documentation 
sity administrator, the analyst needs to document it, 
including annotations about the purpose and ratio- 
nale of classes and attributes. To document it, she 
configures an output text type whose content and 
structure is compatible with her company's stan- 
dard for OO documentation. An example of a de- 
scription obtained in modifying the text plan of Fig- 
ure 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 re- 
quired is not retrievable from the CASE tool object 
model (section Purpose), and tables composed both 
of information generated automatically and informa- 
tion entered manually (section Attributes). The ana- 
lyst 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. 
4 How MODEX Works 
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 
Figure 5: MODEx Server Architecture 
• Text Plan Editing. This generates an HTML doc- 
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 per- 
manently in the library of text plans and can be 
used to generate descriptions. In this representa- 
tion, 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 
MoDEx. 
alidation-Class) 
Ti~e, 
User Text 
Ti~e Schema ~itle Schema 
i I I I 
User Text Relations-Text User Text Examples-Short 
Figure 6: Macro-Stucture for Text Plan of Figure 3 
• Object Model Loading. This loads an object model 
specification and generates a document displaying 
the list of classes found in the model. 
• 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 orga- 
nization, while the bottom nodes define its content. 
The text content can be specified as syntactic repre- 
255 
sentations, as table specification and/or as human- 
authored text for the titles and the object model an- 
notations. 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 con- 
stituents (cf. expression For example on Figure 2). 
The resulting text structure is then passed to the 
text realizer which uses REALPRO (Lavoie and Ram- 
bow, 1997), a sentence realizer, to realize each indi- 
vidual syntactic representation in the text structure. 
Finally, a formatter takes the final text structure to 
produce an HTML document. 
• Object Model Annotation Editing. This allows the 
user to edit human-authored annotations of the ob- 
ject model. This editing can be done via links la- 
belled Edit ... which appear in Figure 4. These 
human-authored texts are used by some of the pre- 
defined text functions to generate the descriptions. 
5 Outlook 
MoDEx is implemented in C++ on both UNIX 
and PC platforms. It has been integrated with 
two object-oriented modeling environments, the 
ADM (Advanced Development Model) of the KBSA 
(Knowledge-Based Software Assistant) (Benner, 
1996), and with Ptech, a commercial off-the-shelf 
object modeling tool. MoDEx has been fielded at a 
software engineering lab at Raytheon, Inc. 
The evaluation of MoDEx is based on anecdotal 
user feedback obtained during iterative prototyping. 
This feedback showed us that the preferences regard- 
ing the content of a description can vary depending 
on the organization (or type of user). The control 
that MoDEx gives over the text macro-structure is 
one step toward satisfying different types of text re- 
quirements. We are currently extending MoDEx in 
order to give the user a better control over the text 
micro-structure, by replacing the set of predefined 
C++ text functions with customizable ASCII spec- 
ifications. This feature should make MODEx more 
easely portable among different types of users. In 
addition, we intend to port MODEX to at least two 
new OO modeling environments in the near future. 
Acknowledgments 
The first version of MoDEx for ADM was supported by 
USAF Rome Laboratory under contract F30602-92-C- 
0015. General enhancements to the linguistic machin- 
ery were supported by SBIR F30602-92-C-0124, awarded 
by USAF Rome Laboratory. Current work on MODEx 
is supported by the TRP-ROAD cooperative agreement 
F30602-95-2-0005 with the sponsorship of DARPA and 
Rome Laboratory. We are thankful to K. Benner, M. 
DeBellis, J. Silver and S. Sparks of Andersen Consult- 
ing, and to F. Ahmed and B. Bussiere of Raytheon Inc., 
for their comments and suggestions made during the de- 
velopment of MoDEx. We also thank T. Caldwell, R. 
Kittredge, T. Korelsky, D. McCullough, A. Nasr and M. 
White for their comments and criticism of MoDEx. 

References 

Benner, K. (1996). Addressing complexity, coordina- 
tion, and automation in software development with the 
KBSA/ADM. In Proceedings of the Eleventh Knowledge- 
Based Software Engineering Conference (KBSE-96), 
Syracuse, NY. 

Cattell, R. G. G., editor (1994). The Object Database 
Standard: ODMG-93. Morgan Kaufman Publishers, San 
Mateo, CA. 

Davis, A. M. (1993). Software Requirements. Prentice- 
Hall, Inc., Upper Saddle River, N J, revision edition. 

Gulla, J. (1993). Explanation Generation in Information 
Systems Engineering. PhD thesis, Norwegian Institute 
of Technology. 

Johnson, W. L. and Erdem, A. (1995). Interactive ex- 
planation of software systems. In Proceedings of the 
Tenth Knowledge-Based Software Engineering Confer- 
ence (KBSE-95), pages 155-164, Boston, Mass. 

Johnson, W. L., Feather, M. S., and Harris, D. R. 
(1992). Representation and presentation of requirements 
knowledge. IEEE Transactions on Software Engineer- 
ing, pages 853-869. 

Kim, Y.-G. (1990). Effects of Conceptual Data Modeling 
Formalisms on User Validation and Analyst Modeling 
of Information Requirements. PhD thesis, University of 
Minnesota. 

Lavoie, B., Rainbow, O. and Reiter, E. (1996). The 
MODELEXPLAINER. In Demonstration Notes of International Natural Language Generation Workshop (INLG-96), Hermonceux Castle, Sussex, UK. 

Lavoie, B. and Rainbow, O. (1997). A Fast and Portable 
Realizer for Text Generation Systems. In Proceedings of 
the Fifth Conference on Applied Natural Language Processing (ANLP-97) , Washinghton, DC.. 

Martin, J. and Odell, J. (1992). Object-Oriented Analy- 
sis and Design. Prentice Hall, Englewood Cliffs, NJ. 

Petre, M. (1995). Why looking isn't always seeing: 
Readership skills and graphical programming. Commu- 
nications of the ACM, 38(6):33-42. 

Scott, D. and de Souza, C. (1989). Conciliatory planning 
for extended descriptive texts. Technical Report 2822, 
Philips Research Laboratory, Redhill, UK. 

Swartout, B. (1982). GIST English generator. In Pro- 
ceedings of the National Conference on Artificial Intelli- 
gence. AAAI. 
