File Information
File: 05-lr/acl_arc_1_sum/cleansed_text/xml_by_section/metho/97/a97-1038_metho.xml
Size: 29,644 bytes
Last Modified: 2025-10-06 14:14:30
<?xml version="1.0" standalone="yes"?> <Paper uid="A97-1038"> <Title>CogentHelp: NLG meets SE in a tool for authoring dynamically generated on-line help</Title> <Section position="3" start_page="0" end_page="257" type="metho"> <SectionTitle> 2 Software Engineering Goals </SectionTitle> <Paragraph position="0"> From a software engineering perspective, we set out to achieve three main goals in designing CogentHelp, each of which has various aspects. The first of these goals is end user-oriented, whereas the latter two are developer-oriented.</Paragraph> <Paragraph position="1"> The first goal is to promote quality in the resulting help systems, which includes promoting * Consistency -- the grouping of material into help pages, the use of formatting devices such as headings, bullets, and graphics, and the general writing style should be consistent throughout the help system; * Navigability -- the use of grouping and formatting should make it easier to find information about a particular GUI component in the help system; * Completeness -- all GUI components should be documented; * Relevance -- information should be limited to that which is likely to be of current relevance, given the current GUI state; * Conciseness -- redundancy should be avoided; * Coherence -- information about GUI compo null nents should be presented in a logical and contextually appropriate fashion.</Paragraph> <Paragraph position="2"> The second goal is to facilitate evolution, which includes facilitating * Fidelity -- the help author should be assisted in producing complete and up-to-date descriptions of GUI components; * Reuse -- wherever possible, the help author should not have to write the same text twice. The final goal is to lower barriers to adopting the technology, which has principally meant providing an authoring interface which makes the benefits of the system available at a reasonable cost in terms of the understanding and effort required of the help author.</Paragraph> </Section> <Section position="4" start_page="257" end_page="258" type="metho"> <SectionTitle> 3 Automated Documentation </SectionTitle> <Paragraph position="0"> The main idea of CogentHelp is to have developers or technical writers author the reference-oriented part of an application's help system 1 in small pieces, indexed to the GUI components themselves, instead of in separate documents (or in one monolithic document). CogentHelp then dynamically assembles these pieces into a set of well-structured help pages for the end user to browse.</Paragraph> <Paragraph position="1"> The principal advantage of this approach is that it makes it possible to keep the reference-oriented part 1By the reference-oriented part, we mean the part of a help system which describes the functions of individual windows, widgets, etc., as opposed to more general or more task-oriented information about the application; other than providing an easy way of linking to and from CogentHelp-generated pages, CogentHelp leaves task-oriented help entirely to the author.</Paragraph> <Paragraph position="2"> of an on-line help system up-to-date automatically, since both the application GUI and the documentation can be evolved in sync. This benefit of generating both code and documentation from a single source 2 has long been recognized, both in the NLG community (cf. Reiter and Mellish, 1993; Moore, 1995; and references therein) and in the SE community, where it is recognized under the banner of literate programming tradition (Knuth, 1992). Other important benefits stem from supporting the separation of the content of the document to be generated (descriptions of individual components) from the structure of the document (how the content is distributed and formatted): this allows the author to focus on writing accurate component descriptions, and avoid much of the drudgery involved in creating a complex hypertext document manually.</Paragraph> <Paragraph position="3"> To better understand where CogentHelp fits in, it is instructive to compare it with the closest reference points in the NLG and SE communities. On the NLG side, there is the Drafter system (Paris and Vander Linden, 1996), which generates drafts of instructions in both English and French from a single formal representation of the user's task. Drafter is considerably more ambitious in aiming to automate the production of multilingual, task-oriented help; at the same time, however, Drafter is more limited in that it is not evolution-oriented, aiming only to generate satisfactory initial drafts (whence its name).</Paragraph> <Paragraph position="4"> This is in large part due to the fact that Drafter's input is centered around task representations which are not typically used for GUI-level tasks in software engineering practice; in contrast, nearly every GUI builder provides some form of GUI resource database which could be used as input to CogentHelp.</Paragraph> <Paragraph position="5"> On the SE side, the nearest reference points are a bit more distant, as CogentHelp has more in common with developer-oriented tools such as the javadoc API documentation generator distributed with Sun Microsystems' Java Developers Kit (Friendly, 1995) than with currently available help authoring tools. While several current GUIdevelopment environments include tools which generate an initial, &quot;skeleton&quot; help system for an application (with topics that correspond to the widgets in the GUI), to our knowledge CogentHelp is the first operational prototype to implement the &quot;evolution-friendly&quot; properties of a tool like javadoc in a system for generating end user-level documentation.</Paragraph> <Paragraph position="6"> Unlike the &quot;skeleton generators&quot; mentioned above, 2Note that this &quot;single source&quot; need only be virtual -- physically single-source code and documentation can have its drawbacks, which are not however inherent to the approach (Priestley et al., 1996).</Paragraph> <Paragraph position="7"> which require the help author to start from scratch each time the skeleton is regenerated in response to GUI modifications, CogentHelp supports help authoring throughout the software life cycle.</Paragraph> </Section> <Section position="5" start_page="258" end_page="258" type="metho"> <SectionTitle> 4 System Overview </SectionTitle> <Paragraph position="0"> CogentHelp takes as input various human-written text fragments (or &quot;help snippets&quot;) indexed to GUI resource databases, which provide some useful helprelated information in the form of types, labels, locations and part-whole relations for GUI widgets.</Paragraph> <Paragraph position="1"> CogentHelp generates HTML help files, which can be displayed on any platform for which a Web browser is available. It is designed to support efficient navigation through the help system, through the use of intelligent, functionally structured layout as well as through an expandable/collapsible table of contents and &quot;thumbnail sketch&quot; applet. These points will be elaborated upon below.</Paragraph> <Paragraph position="2"> CogentHelp operates in two modes: a &quot;static&quot; mode, which does not make use of run-time information, and a &quot;dynamic&quot; mode, which uses widget run-time status information to produce more specialized, contextually appropriate messages. The static mode is useful in the authoring process, since it displays all available help information and has simpler architectural requirements.</Paragraph> <Paragraph position="3"> In evolving the design of CogentHelp, we have employed a rapid-prototyping approach in working with our TRP/ROAD 3 consortium partners at Raytheon, who are serving as a trial user group.</Paragraph> <Paragraph position="4"> The full CogentHelp component architecture and dependencies reflects the particular requirements of this group, and are as follows. CogentHelp itself is a hypertext server written in Java, making it highly cross-platform. CogentHelp currently works with applications built using the Neuron Data cross-platform GUI builder; while it is not dependent on this product in any conceptually substantial way, using other GUI builders would require a porting effort. To retrieve run-time information, CogentHelp uses Expersoft's PowerBroker ORB for inter-process communication; in comparison to the Neuron Data connection, other IPC methods could be more easily substituted. Finally, CogentHelp displays hyper-text in Netscape Navigator, using HTTP to mediate access to the dynamically generated texts; since Netscape Navigator remains the most widely used cross-platform browser, we have yet to investigate using other browsers.</Paragraph> <Paragraph position="5"> 3A DARPA-sponsored Technology Reinvestment Program for Rapid Object Application Development, led by Andersen Consulting.</Paragraph> </Section> <Section position="6" start_page="258" end_page="262" type="metho"> <SectionTitle> 5 NLG Techniques </SectionTitle> <Paragraph position="0"> Although CogentHelp is by no means a typical NLG system -- insofar as it is incapable of generating useful texts in the absence of human-authored help snippets -- it does employ certain natural language generation techniques in order to support the software engineering goals described above. These techniques fall into two categories, those pertaining to knowledge representation and those pertaining to text planning.</Paragraph> <Section position="1" start_page="258" end_page="260" type="sub_section"> <SectionTitle> 5.1 Knowledge Representation </SectionTitle> <Paragraph position="0"> In developing CogentHelp, we have taken a minirealist approach to knowledge representation following a methodology for building text generators developed over several years at CoGenTex. As will be explained below, this approach has led us to (i) make use of what amounts to a large-grained &quot;phrasal&quot; lexicon and (ii) devise and implement a widget-clustering algorithm for recovering functional groupings, as part of an Intermediate Knowledge Representation System (IKRS).</Paragraph> <Paragraph position="1"> As Milosavljevic et al. (1996) argue, to optimize coverage and cost it makes sense to choose an underlying representation which * makes precisely those distinctions that are relevant for the intended range of generated texts; and * is no more abstract than is required for the inference processes which need to be performed over the representation.</Paragraph> <Paragraph position="2"> They go on to argue that besides eliminating a great deal of unnecessary 'generation from first principles,' this approach complements their use of a phrasal lexicon (Kukich, 1983; Hovy, 1988) at the linguistic level.</Paragraph> <Paragraph position="3"> Applying essentially the same approach to the design of CogentHelp, we first determined that for the intended range of generated texts it suffices to associate with each widget to be documented a small number of atomic propositions and properties, identifiable by type. Next we determined that since no inference is required beyond checking for equality, these propositions and properties can be conflated with their linguistic realizations- i.e., the indexed, human-authored help snippets CogentHelp takes as input. While we did not originally think of CogentHelp's collection of input help snippets as a phrasal lexicon a la Milosavljevic et al., in retrospect it becomes evident that this collection can be viewed as tantamount to one; of course, since these snippets vary in size from phrases to paragraphs, the term &quot;phrasal&quot; is not entirely accurate.</Paragraph> <Paragraph position="4"> The types of snippets in current use include a one-sentence short description of the relevant GUI component; a paragraph-sized elaboration on the short description; various phrase-sized messages concerning the conditions under which it is visible or enabled, if appropriate; and a list of references to other topics. In the case of the phrase-sized messages, each of these fields is accompanied by a syntactic frame which prompts the author to provide consistent syntax -- for example, entries in the WHEN_ENABLED field should fit the frame This element is enabled when To facilitate equality checking and promote text reuse, a mechanism is provided enabling the author to alias the message for one widget to that of another. null To enhance the modularity and robustness of a practical text generator, Korelsky et al. (1993) argue for the use of an Intermediate Knowledge Representation System (IKRS, pronounced &quot;Icarus&quot;) to bridge the gap between what the text planner would like to access and what is actually found in the information base of an application program. A remarkably similar idea has been independently developed by Lester and Porter (1996), under the heading of KB Accessors.</Paragraph> <Paragraph position="5"> One purpose of an IKRS, Korelsky et al. suggest, is to provide a component in which to locate domain-level inferencing not provided by the application program. Note that while this type of inferencing is motivated by text planning needs, it is still about the domain rather than about natural language communication, and thus does not belong in the text planner itself.</Paragraph> <Paragraph position="6"> In developing CogentHelp, we encountered a need for just this sort of inferencing in order to support sensible layout. The problem we faced was how to logically arrange descriptions of widgets within a help page (or set of help pages) describing a window, which is the basic unit of organization in Cogent-Help. As will be explained below, grouping widgets by type was considered inadequate, because doing so would obscure functional relationships between widgets of different types. A naive spatial sorting was likewise considered inadequate, as this would inevitably separate elements of a functional group appearing in a certain area of the window. Unfortunately, since these functional groups are often not explicitly represented in GUI resource databases, we appeared to be at an impasse.</Paragraph> <Paragraph position="7"> To illustrate the problem, consider the sample application window shown in Figure 1, from a prototype of an application under development by our trial user group at Raytheon. This window, whose purpose is to allow a manufacturing shop floor foreman to assign operators to parts, is organized as follows: on the left there are two list boxes for operators (1, 2), with buttons beneath them to access information about these operators (3, 4, 5, 6); on the right there are two list boxes for parts (9, 10), with buttons beneath them to access information about these parts (11, 12); in the middle there are two buttons for making and removing assignments (7, 8); towards the bottom there is a list box showing the assignments made so far (of which there are none here -- 13); and at the bottom there are standard buttons such as Save and Done (14, 15 -- the Help button would go here). Given this organization, consider first arranging descriptions by type, and alphabetizing: besides cutting across the implicit functional groupings, arranging descriptions in this way would end up putting the two View K-Factors buttons (4, 11) in sequence, without any indication of which was which! Now consider a simple top-down, left-to-right spatial sort: again, this would inevitably yield a rather incoherent ordering, such as the Operators without Work list box (1), the Hot Parts list box (9), the Assign button (7), the Operators on Jobs list box (2), the Parts list box (10), the Remove Assignment button (8), etc.</Paragraph> <Paragraph position="8"> The solution to this problem was to develop, as part of our IKRS, a method of recovering these func- null tional groups using spatial cues as heuristics; the reason this approach might be expected to work is that in a well-designed GUI, functionally related widgets are usually clustered together spatially in order to make the end user's life a bit easier. We began with the fairly standard hierarchical agglomerative algorithm found in (Stolcke, 1996). Stolcke's algorithm is an order n ~ one that iteratively merges smaller clusters into bigger ones until only one cluster remains; new clusters are formed out of the two nearest clusters in the current set, ensuring that the results are independent of the order in which clusters are examined. After some experimentation, we modified this algorithm to better suit our needs, resulting in the following three differences: (i) to create clusters with more than two elements, we continue adding elements to the newly created cluster until a certain distance threshold is exceeded; (ii) we represent the new cluster using its bounding box, rather than using an average of its elements; and (iii) we restrict the clustering to not operate across explicit groups, such as those formed using panels.</Paragraph> <Paragraph position="9"> With any clustering approach, there is always the tricky matter of determining a suitable distance measure. After trying out a variety of features, what we found to work surprisingly well was a simple weighted combination of proximity, alignment and type identity. In particular, in a test suite of around 15 windows provided to us by our trial user group, we obtained reasonable results (no egregiously bad groupings) on all of them without undue sensitivity to the exact weights. In the case of the window shown in Figure 1, the clustering procedure performs exactly as desired, yielding precisely the groupings used in the description of this window given above</Paragraph> <Paragraph position="11"> Once the IKRS has heuristically recovered clusters of widgets likely to form a functional group, these clusters -- as well as any explicitly represented groups, e.g. widgets contained within a panel of a window -- can be used as a basis for help layout, as discussed below.</Paragraph> </Section> <Section position="2" start_page="260" end_page="262" type="sub_section"> <SectionTitle> 5.2 Text Planning </SectionTitle> <Paragraph position="0"> At the core of CogentHelp is the text planner. The text planner builds up HTML trees starting from an initial goal, using information provided by the IKRS, following the directives coded in CogentHelp's text planning rules. These HTML trees are then linearized into an ascii stream by a separate formatter, so that they can be displayed in a web browser (cf.</Paragraph> <Paragraph position="1"> Section 4).</Paragraph> <Paragraph position="2"> The text planner is constructed using Exem- null plars for Java, a lightweight framework for building object-oriented text planners in Java which has been developed in parallel with CogentHelp (White, 1997). In this framework, text planning rules -- the exemplars, so-called because they are meant to capture an exemplary way of achieving a communicative goal in a given communicative context -- are objects which cooperate to efficiently produce the desired texts. While space precludes a detailed description, it is worth noting that Exemplars for Java supports abstraction, specialization and content-based revisions, all of which have proved useful in the present effort.</Paragraph> <Paragraph position="3"> In developing the exemplars for CogentHelp, we have made use of three NLG techniques: structuring texts by traversing domain relations, automatically grouping related information, and using revisions to simplify the handling of constraint interactions. The first two of these make life simpler for the end user, while the third makes life simpler for the developer. When text structure follows domain structure, one can generate text by selectively following appropriate links in the input (Paris, 1988; Sibun, 1992). In the case at hand, we have chosen to use the group and cluster structure combined with a top-down, left-to-right spatial sort: while such a spatial sort alone is insufficient, as we saw above, a spatial sort which respects functional groups turns out to work well.</Paragraph> <Paragraph position="4"> Returning to the example of Section 5.1.2 (regarding the window shown in Figure 1), traversing the clusters in this way yields a listing which (naturally!) mirrors the order and groupings of the one-sentence description of the window's organization we have provided -- that is, following a general description of the window, there are descriptions of the two operators list boxes (1, 2), followed by descriptions of the four buttons providing additional information on operators (3, 4, 5, 6), followed next by the part list boxes (9, 10) and the buttons associated with them (11, 12), and so on. This is (partially) illustrated in Figure 2, which shows a sample CogentHelp-generated help topic. Note that the list of widgets in the dynamic TOC on the left side of the page is arranged according to this traversal; consequently, stepping through the contents (using the TOC or the Next button) for this window will lead from widget to widget and cluster to cluster in a sensible fashion. In the particular topic shown, the user has reached the second button (View K-Factors) of the group of four buttons beneath the Operators list boxes, as can be seen from the highlighting in the thumbnail sketch applet (cf. Section 6).</Paragraph> <Paragraph position="5"> The use of domain structure-driven text planning is central to supporting the software engineering goals identified in Section 2. Rather obviously, generating-by-rule helps to achieve consistency, completeness and fidelity, eliminating much mind-numbing drudgery along the way. A bit less obvious, perhaps, is the fact that this technique should help to achieve navigability and coherence: by presenting descriptions of widgets in a natural order -- i.e., in the order in which the user is apt to encounter them in scanning the GUI -- we hope to make it easier for the user to find desired information; and, by keeping together descriptions of widgets which are heuristically determined to be functionally related, we hope to make it easier for the user to quickly grasp the organization of both the interface and the on-line help.</Paragraph> <Paragraph position="6"> Grouping related information and presenting shared parts just once is a well-known NLG technique for achieving conciseness and coherence (Reiter and Mellish, 1993). In a reference-oriented document such as an on-line help system, similar or identical descriptions will often be appropriate for elements which have similar or identical functions. To indicate these similarities, as well as to save space, it makes sense to group these descriptions when possible. null As mentioned in Section 5.1.1, we allow developers to alias messages to promote text reuse, as well as to facilitate equality checking. When the text planner detects (via the IKRS) that a phrase-sized message (such as T0_ENABLE) is the same for a group of widgets, it generates a description that applies to the whole group, rather than repeating the same description several times in close proximity. Note that this group description is made possible by the use of a phrasal lexicon, which has been designed to allow the author's messages to make sense in a variety of contexts.</Paragraph> <Paragraph position="7"> To illustrate, let us have another look at Figure 2.</Paragraph> <Paragraph position="8"> In the upper right frame of the page, note that there is the following description of how to enable all of the four buttons below the operators list boxes, rather than a repetition of the same message four times in close proximity: These commands are currently disabled.</Paragraph> <Paragraph position="9"> To enable them, select exactly one operator in either the Free Operators list box or the Working Operators list box.</Paragraph> <Paragraph position="10"> This group-level description appears here because (i) the author, realizing that these buttons are enabled under the same conditions, entered the T0_ENABLE message &quot;select exactly one operator in either the Free Operators list box or the Working Operators list box&quot; for one button, and aliased this message for the other; and (ii) the text planner, detecting (via the IKRS) that the TO_ENABLE messages for the entire group were the same, and that these buttons were currently disabled (a run-time fact), prepended &quot;These commands are currently disabled. To enable them,&quot; to the shared message to yield what appears in Figure 2.</Paragraph> <Paragraph position="11"> While the central use of domain structure-driven text planning makes it possible to generate text in a relatively straightforward, top-down fashion, as variations are added a one-pass top-down approach can become cumbersome. The reason why is this: In evolving the text planning rule base, it makes sense to localize decisions as much as possible; however, to handle rule interactions in a single pass, one is forced to centralize these decisions (which can become cumbersome). To simplify matters, it is often appropriate to generate an initial version naively, then carry out revisions on it in a subsequent pass (cf. Robin, 1994; Wanner and Hovy, 1996).</Paragraph> <Paragraph position="12"> In CogentHelp, interactions that are cumbersome to anticipate arise in dealing with the various optional phrase-sized messages whose inclusion conditions differ between the static and dynamic mode. To elaborate, let us consider once more the help page shown in Figure 2. Had the four buttons described in the lower right frame been enabled rather than disabled (at run-time), the group-level T0_.ENABLE message would have simply been left out, in order to en- null hance relevance and conciseness; 4 on the other hand, had this page been generated in static mode (where such run-time conditions are not known), the text planner would have again included the description, though this time with the less specific &quot;To enable these commands,&quot; prepended instead. Now, since the various messages associated with a widget have slightly different inclusion conditions, it makes sense to localize these inclusion conditions to a text planning rule for each message (the common parts of these conditions are shared via inheritance). At the same time, however, there is a need to know whether any of these messages will in fact appear, in order to decide whether to include the second paragraph in the upper right frame, as well as the italics element. In a one-pass top-down approach, this need would force the various inclusion conditions to be cumbersomely centralized; with revisions, in contrast, one can simply add the paragraph and italics element during the first pass, then check during a second pass whether any of the optional messages for this paragraph did in fact appear, removing the superfluous HTML elements if not.</Paragraph> </Section> </Section> <Section position="7" start_page="262" end_page="262" type="metho"> <SectionTitle> 6 Authoring </SectionTitle> <Paragraph position="0"> In informal usability tests, we have gathered much useful information about areas in which CogentHelp could be improved -- the most important of these being ease of authoring. A previous version of the authoring interface, which relied on the resource editor of the Neuron Data GUI builder, proved unsatisfactory, as it (i) required excessive clicking for the author to navigate from snippet to snippet, and (ii) failed to provide sufficient context, making it unnecessarily difficult for the author to adhere to the CogentHelp authoring guidelines.</Paragraph> <Paragraph position="1"> The current authoring interface, shown in Figure 3, uses CogentHelp's existing architecture (together with the HTTP forms protocol) to allow the user to edit the text snippets for each widget in substantially the same context they would inhabit in generated help topics. This design provides maximal realism for the author, especially since one can switch between editing and browsing mode at the click of a button to preview the generated help.</Paragraph> <Paragraph position="2"> Another feature illustrated in Figure 3, as well as Figure 2, owes its inspiration to our trim user group at Raytheon. Our users were concerned about the ease of visual navigation of help pages, and had experimented with using manually coded (and 4With a perfectly intuitive GUI, the user would never need to know this information, as commands would always be enabled when the user expects them to be.</Paragraph> <Paragraph position="3"> thus difficult to evolve) image maps superimposed over bitmaps of each application window. This concern prompted us to develop an automatically generated &quot;thumbnail sketch&quot; of the current GUI window, which appears in the upper left corner of the help window (in a Java applet along with the table of contents) and contains hyperlinks for each of the widgets on the window (these hyperlinks display the corresponding help topics on the right-hand side). The automatically generated thumbnail images require no intervention on the part of the help author, and thus are guaranteed to be up-to-date; furthermore, their abstract nature gives them certain advantages over actual bitmaps: they do not present information which is redundant (since the actual window in question will usually be visible) or inconsistent (static bitmaps fail to capture widgets which are enabled/disabled or change their labels in certain situations).</Paragraph> </Section> class="xml-element"></Paper>