File Information
File: 05-lr/acl_arc_1_sum/cleansed_text/xml_by_section/metho/96/c96-2124_metho.xml
Size: 17,089 bytes
Last Modified: 2025-10-06 14:14:12
<?xml version="1.0" standalone="yes"?> <Paper uid="C96-2124"> <Title>Building Knowledge Bases for the Generation of Software Documentation *</Title> <Section position="4" start_page="734" end_page="735" type="metho"> <SectionTitle> 3 Representing the users' tasks </SectionTitle> <Paragraph position="0"> Early in the I)I{,AFTEI{ projee:t, we conducted interviews with technical authors (me)stly soft;ware clocmnentation sl)ecialists) in order I;t) understand the docmnentation process as it, currently exists, to see', if an authoring tool wouht be hell}tiff , and if so how it inight be used. We found that technical authors stm't the documentation process by le;~rning how 1;o use the interface in question, constructing a user-oriented mental model of the product.</Paragraph> <Paragraph position="1"> They Kequently have no input or, her than the software itself. The authors indicated that they wouhl weleollle tools to hell) them collect the apl)ropriate information and create a formal representation of the resulting model. Such a representation wouhl supt)ort iterative construction of the doe,lmetltation and intbrmat:ion reuse.</Paragraph> <Paragraph position="2"> Building our draft;lag tool, therefore, required us first, to determine how to represent the model of a task, and then to build tools for creating and manipulating this model. Given that the gemeral structure of instructional texts is hierarchical, we chose a representation that e.xpresses a hierart:hy of goals and sub-goals. The reI)resentation is thus similar to the (;raditi(mal structures found in AI plalming, e.g., (Sacerdoti, 1977), and also to task models used in interface design, e.g., (Card et al., 1983). Because user documentation frequently inchldes information other than the raw actions to be performed, our representation allows authors to include information not typically foulld in traditional plan rel)resentations such as: /1seroriented motiw~tional goals, helpflfl si(le-efl'e(;ts, and general COlllliletltS.</Paragraph> <Paragraph position="3"> As an example, consider the rei)resentatitm of a sub-set of the procedure for retying a new file in a Microsoft; WoM-like editor shown in Figm:e 1.</Paragraph> <Paragraph position="4"> The owl,1 boxes in the figure ret)resent actions anti the rectangh',s represent plans. Ea('h of the action nodes in this sl;rueture rel)resent inter(:omw,(:i;e(t complexes of procedural and descriptive instances.</Paragraph> <Paragraph position="5"> For examl)le , the main us(;r goat of saving a do(;u.meat, represented in the figure by the action node &quot;Save ;L Document&quot;, is implemented in the knowledge base as a comple, x of instances repres(mting the act;ion being tmrformed (in this case saving), tim agent who performs action (the reader), the t)atient on whom the aetioll is performed (the current doeunmnt), etc. All of this itlforination is required to generate expressions of the action, but 1)resenting it would overly complicate the graph.</Paragraph> <Paragraph position="6"> The links actually shown in tilt; figure are based on the, procedural relations in the domain model.</Paragraph> <Paragraph position="7"> For exalnple, the I)lan for saving a document (Save-l)ocument-Plan) is linked to its goal (Save A Do(:umelfl;), to its precondition (()t)e,n-Savc-As), and to its sul)-at:tions of typing a name for the (;llrrellt document (Tyl)e-Document-Name), opening l;he fohler in which it is to t)e saved (Ot)ei> l,'ohler), and clicking the Save tmtton (Choose-Save-Ilutton). The precondition (Open-Save-As) must be tmrformed before the sub-steps may t)e attempted and is in turn linke(t to fllrther sub-plans (Choosing-Plan and Clicking-Plan). This indicates that the Save-As dialog box may be ope, ned by either choosing the Save option from the file, melm (Choose-Save-()t)tion) or (',licking the Save butttm on the tool bar (Click-Save-h:on).</Paragraph> <Paragraph position="8"> 'Fhis task model represents the procedures that a user might perform when using an at)t)li(;ation and is tim basis for generating user-(x;ntrt:(1 (lt)cumeal;aLien, slt(;h as olle of I)I{AFTEI\['s texts shOWll in Figm'e 4. It includes the users' high-level goals (e.g., &quot;save a document&quot;) as well as their lowle, vel interf;tce manipulations (&quot;choose the save lmtton&quot;).</Paragraph> <Paragraph position="9"> 4 Input from the Design Process In our earlier work, we provided tools that supl)orted 1;t1(; construction of the task nlodel t)y hand (Paris et al., 1995). This went some way to addressing the, technical aut;hors' desire for a formal model and tools to lmild it.. Building the model Dora scratch, howe, ver, even with the, help of our menu lmsed interface, was a tedious and lengthy process which could potentially have rendered tile I)I{AFTEI{ system impractical. There was a clear need for facilities to ease the input task. In line with this, we noticed that certain elements of the model were also present in the specifications developed in user interface design environments. Indeed, we found that a number of the actions and objects in the model could be automatically acquired from a design tool, thus providing basic building blocks from which the flfll model could be constructed.</Paragraph> <Paragraph position="10"> 3b illustrate this idea, we have built our example document editor application in VisualWorks, a widely available interface design environment (Vis, 1994). This tool allows one to define the windows, dialog boxes, and other widgets relevant for the application under develot)ment, and produces a prototype of the interface thus specified.</Paragraph> <Paragraph position="11"> Its output also includes declarative specifications of all the widgets. These specifications are thus available to be exploited by other systems. In partieular, we found that these specifications could be readily transformed into a form appropriate for the knowledge base required by a text; generation system such as DRAFTEI/.. In our examt)le then, we build a VisualWorks mock-up of our word processing application, and I)RAI,'TEK derives task model instmmes for all the windows and widgets in (;he application (e.g., the Save-As dialog box and all its widget, s) directly fl'om tile SmallTalk source code.</Paragraph> <Paragraph position="12"> DItAFTEI{ is also able to infer the basic interface actions that can be performed on the various interface widgets and creates task model instances for them as well. For example, the system automatically defines a clicking action instance for any &quot;button&quot; on the interface. Similarly, it c.reates opening and (:losing actions for all &quot;windows&quot;. Although this set of instances does not ret)resent all tile information that could, in principle, be derived from the SmallTalk specitications of the editor application, it nevertheless simplifies greatly the technical author's task of knowledge specification by providing the huilding blocks from which higher-level procedures can be defined. In tile case of out' admittedly simple example, seven of the nine actions in the procedural structure are automatically specified. The author is required to specify only the main user goal action and the three plan nodes. This is, t, hercfore, a step towards aut;omatically building the knowledge base required for the generation system. It is also a step towards integrating the (lesign and documentation processes, which is now widely recognised as being desirable. In our current work, we are investigating how more of the design knowledge call be made accessible ~md uiMel'standable to the technical authors, and what other tools would further facilitate tile authors' task. We are also looking at a tighter integration of the design and documentation processes, one in which tile individuals involved work together during design.</Paragraph> </Section> <Section position="5" start_page="735" end_page="736" type="metho"> <SectionTitle> 5 DRAFTER </SectionTitle> <Paragraph position="0"> We. now describe I)I\].AFTEI{> a technical authoring tool which supports the construction of tile task model discussed above and the drafting of multi-lingual instructions from that inodel. We will focus on how it supports the author in augmenting the information automatically acquired Dora the interface design tool. I)RAFTEI/,'S general architecture, shown in Figure 2, is based on two inain processing modules: Tile Author Interface (shown oil the fitr left of the diagram) allows authors to build a task model and to control the drafting process.</Paragraph> <Paragraph position="1"> The Drafting rlbol (shown on tile far right of the diagram) comI)rises two major components: the Text Planner and the Tactical Generator. The Te.xt Planner determines tile (:o,~t,e.nt and structure. The. knowle<lge base (in the middl<: of (;}m figure) mMerlies the task model built by the (;<x:hni<:al au= Lhor. The DrafLing Tool takes this reprcscni;at, ioil as input, and produces English an<l f,Y=ench draf'ts of t, he appropriaW, tul;orial inslxu<:tions. In this s<:ction we de(;ail ea<',h of (;hese (:omponenl;s in (;he <'.on(,ext of an exampl<,,</Paragraph> <Section position="1" start_page="736" end_page="736" type="sub_section"> <SectionTitle> 5.1 The Knowledge Base </SectionTitle> <Paragraph position="0"> The knowl(,<tge base sut)porl;s (;he (:oilst;ru(;l;ion of (;he (;ask mo<M discussed above. \[(; is an hierarchical stru(:t, ur<: imph:menl;e<l in I,OOM (MacGr(:gor, 1988). Th(; root is l,h(; l)(mman M(:rg<:(l Upl)er Model (Bal;eman, 1995), an ontology <)f <listinctions relevalfl; in (;xpressing actions, (>t)j(x;l;s, and qualities in na.l;urat language. The know\](;dge base <:onl;ains t'urther layers corr<:st)ouding 1;o: (1) (;h(: conc(;t)l;s and relal;ions general to all insLru(:l;ions; (2) those g<;ncral only Ix) software im;erfa(:cs; an<t (3) l;hose Sl)(:<:iti<&quot; t;o the chos(,qi soft;wa.r(~ apt)li(:al;ion d<)mains (in ore' case text i)ro(:(:ssing (;<)<)Is). Using (;lle I)I/AF'I'EI/. inl;erfa(:e, (,e(:hnical aul;htns specify hi(!)'archi<:al (;ask m(>(Ms, su(:h as (;he one shown in Figur(! 1, 1)y building nodes and <'.<mne(:l;ing l;hem wil;h l;h(,, appropriate I))'o(:edm'al I'C,lal;ions. The low-le.vel buihling blocks of l;he (;ask model are derived automal;i(:atly, and I)I{AI,'TI.;II.</Paragraph> <Paragraph position="1"> alh)ws (;he (x'~chnical alll;hor 1;o (:Olltl(l(:(; \[,h(}ill and a<ld higherqevel (;ask inforula(;ion as ai)prot)riat(: , using an inl;(:rfa(:e bas(:<l on (:onlxolled language and (;he use. of meims (x) guid(', l;he aul;hor.</Paragraph> </Section> <Section position="2" start_page="736" end_page="736" type="sub_section"> <SectionTitle> 5.2 The Interface </SectionTitle> <Paragraph position="0"> This 1;ool Inak<'.s the st;ru(:tm'e of t;hc knowledge base on whi<:h l;h<: \[;ask model is lmill; mot(: ac cessiblc 1;<> l;he aul;hor. I(; allows the aul;hor (;o perform t,wo basic tasks: (1) sp<'.<:ii~ying (;he ac.</Paragraph> <Paragraph position="1"> t, ion nodt:s at)pearing in l;hc Sl;l'tlt;l;llrc all(\[ Ho\[; yel; <t<:rivcd fl'OlIl 1;11(: inl;erfact: designed tool; and (2) linking existing nodes (,ogt:l;ht:r wit, h (;he al)propria.(;(; plan insi;anc(;s and relal,ions. The. tirs(; of (;hese (;asks is lmrfornmd using a. <:ontrolle<t nalalra.1 bm guage inl;erfa<> wlfile the s<'.<:<md is done wit;h a <lialog box lllc(:haltisill.</Paragraph> <Paragraph position="2"> Specifying (;tie 11(}(l(;s at)l)eal.illg ill t;he t;ask model involves stmcit'ying a flfll complex of till guist, ic cntil;ics and roh;-filh;rs (<;.g., a<:l.<)rs, acl;(~es, desl;inai;ions). Be.<:ause. l;his stru<:tm'c may in<:hah,.</Paragraph> <Paragraph position="3"> lIially instances inl,ercomlecl, cd lit pot;cnt, ially mt inlalil;ivc ways, w(: have 1)r(>vi<l<:(1 a C(>nlx<>lle(1 Na(> m'al l,anguag<, (CNI,) inlx:r\['ac(: for I;|m mlI;h()r.</Paragraph> <Paragraph position="4"> 7 ;3 7 Tile interface is shown in Figure 3. This interface allows the author to work in terms of sentences rather than in terms of interconnected graphs.</Paragraph> <Paragraph position="5"> Tile figure, for example, shows the author in the process of specifying tile node Save A Document.</Paragraph> <Paragraph position="6"> The top line of text (reader save \[information\]) shows the current state of the CNL specification.</Paragraph> <Paragraph position="7"> Words in brackets must be further specified. This is done by clicking on the word and selecting the appropriate pattern from a list of possible expansions. In tile figure, the author has clicked on \[information\] and is presented with a list of the types of information from which \[document\] can be selected. This process is driven by a controlled natural language grammar which specifies possible expansions at each point of tile derivation. The bottom line of text presents a flllly expanded default at each point in the derivation. In the figure, this CNL text is &quot;reader save current document&quot; which could be expressed in English in a mnnber of ways including &quot;Save the current document&quot; and &quot;To save tile document&quot;.</Paragraph> <Paragraph position="8"> Once the action nodes of the graph have been created, or perhaps while they are being created, the author has the ability to link them together using a set of predefined procedural relations: goal, precondition, sub-action, side-effect, warning, and cancellation. This is done with a graphical outlining mechanism. This mechanism allows authors to drag actions from the ACTIONS pane and drop them on the various procedural relation slots in the workspace pane, or, alternatively, to create new actions to fill the slots. The result is a procedural hierarchy such as the one shown in Figure 1.</Paragraph> <Paragraph position="9"> This interface allows the author to specify the procedure in several ways. They may start from the main goal and work down tile structure, or they may start by specifying all the low-level actions and object and work up the structure.</Paragraph> <Paragraph position="10"> The Knowledge Grapher prevents tile author from losing orientation by maintaining the current state of the procedural structure in graphical form. This form is like that shown in Figure 1. Because the nodes are mouse-sensitive, it allows the author to iifitiate construction and maintenance functions by clicking on the appropriate nodes in tile graph. Authors can also invoke tile drafting tool from the graph.</Paragraph> <Paragraph position="11"> 5.2.a The Draft Text Viewer The author may draft multilingual instructions oil any portion of tile procedural structure at any point in the specification process. This task is performed by the Drafting Tool which is briefly described in tile next section. This tool produces a draft of the instructions in English and French. These are presented to the author by tile Draft Text Viewer. The presented text is mousesensitive, allowing the author to access the knowledge base entry for selected part of tile text. In this way, the author can modify the underlying knowledge base while working from the text. In some cases the writer will decide to modify the generated text rather than tile underlying knowledge. For this purpose, a text editor is currently provided.</Paragraph> </Section> <Section position="3" start_page="736" end_page="736" type="sub_section"> <SectionTitle> 5.3 The Drafting Tool </SectionTitle> <Paragraph position="0"> When the author initiates the Drafl;ing Tool (see Figure 2), m~.AF'rl~t calls the Text Planner with the discourse goal: make the user colnpetent to perform tile action specified by the author. The Text Planner selects the content appropriate for the instructions and builds a deep representation of the text to be generated. This portion of the text plalming task is done by tile text planner developed by Moore and Paris (1993). Tile Text Planner then specifies the detailed elements of the.</Paragraph> <Paragraph position="1"> sentence structure. This portion of the task is done by a descendent of IMAGENE (Vander Linden and Martin, 1995).</Paragraph> <Paragraph position="2"> Once complete, the text plans are passed to the Tactical Generator which generates t, he actual text in English and French. This task is performed by tile English and French resources of tile Komet-Penman Multi-Lingual development environment (KPML) (Bateman, 1995), The drafts generated for the example procedure are shown in Figm'e 4.</Paragraph> <Paragraph position="3"> In these texts, we see. that the main nser goal, that of saving a document, is given as a title to the series of steps. Then, the steps to be perfi)rmed to achieve this goal are given. More detail on the, drafting process can be found elsewhere.</Paragraph> </Section> </Section> class="xml-element"></Paper>