EDITION OF STRUCTURED DOCUMENTS IN A HYPER- TEXT ENVIRONMENT Christine Buors Jean-Louis Vignaud ( Cap Gemini Sogeti Group Cap Sesa Research Center ( Chemin du vieux chene ZmST 38240 MEYLAN FRANCE Abstract This paper presents the TWlST (Technical Writer's Integrated Support Tool) project. The system developed within TWlST can be viewed as a high level hypertext system intelface, as well as an environment for the edition of structured documents. This paper explains in which way the two points of view are addressed. In particular, it describes TWIST ob- jectives and the means carried out to reach them. This presentation will led us to introduce the hypertext and stmctured edition concepts Key words Documentation! document! role! stl1lctured edition! hypertext - to provide some help in writing and ns- 1. Introduction ing the documentation during the whole project life cycle. Documentation is one of the key compo- To meet these objectives an environment nents in any project, and particularly in is under specification. This paper pre- the software production domain. Indeed sents the main functionalities which will documents are often the most suitable be supported and the underlying con- and the most reliable communication me- cepts. The choice of the functionalities to dia. Even if some people agree with the be provided has been based on an inves- idea that we generally write too much, tigation of users' needs and on our own we cannot avoid the production of a mini- unf0l1unate experiences. mum set of documents. The current sys- tems carried out in most companies, leave the user feeling uncomfortable: ev- 2. The documentation erybody has experienced, at least one time in his life, the agony of the poor problem ( lonesome writer. We can easily imagine that a good documentation sUpp0l1, or en- Management of documents is a well- vironment, is really a need in any activity known problem in any domain. There are domain (and therefore in the computer generally many kinds of worries: based activities). In the context of ESF (Eureka Software - the problem of writing: a lot of people Factory) this problem has been ad- still dream of a fancy editor allowing the dressed. ESF is an Eureka project use of bold characters without using bar- whose major interest is the management barous signs such as \\f-, $(, and so on, of large projects (that means, projects in- not to mention the luxurious versions al- volving a lot of people). In this context, lowing the "What You See Is What You problems such as activity management Get" ! and control, integration, and man-ma- chine interface design are addressed. The - the problem of homogeneity: how is it aim of the project is to provide companies possible to avoid, in the same project, with a way to design their own software the use of anarchical document formats, environment, according to their specific other than doing a visual control? needs and resources. ESF is a very large project divided into - the problem of consistency: when docu- sub-projects according to different ments share information (for example a themes. TWIST - Technical Writer Inte- schema), how is it possible to control the grated Support Tool - is one of these evolutions of this information in all the sub-projects. As indicated by its name, documents? TWIST deals with documentation man- agement problems. Its two main objec- - the problem of organization: when docu- tives are: ments are finally written (phew!), the - to improve the quality and the produc- last problem is to localize each document tivity of documents within a software among others. This work is really impor- project; tant: particularly in that it introduces a reading order. The documcntation of a project is the - and the last problem (but not the least set of all the documents produced dming 1), how to manage a document all along the project life cycle. To be easily man- its life cycle (versions, archiving, etc.) ? aged these documents must be classi- fied. This classification generally de- In the domain of computer science the pends on the organization of the compa- problem is particularly important since ny, and on the method used to develop any activity is sanctioned by a document. the project. The method, also indicates The set of the documents produced with- which role is responsible for the creation in the whole life cycle of a project there- and the update of a set of documents (or fore constitutes a mountain! In the con- a specific document) and indicates which text of large projects, all the problems roles may consult or modify this set. previously mentioned are increased. ( Before going further, let us introduce a few vocabulary that will be used in this 3.. TWIST functionalities paper. The aim of TWIST is to prove that the A rolc corresponds to the representation current technology in computer science of people functions in the organization of allows the design of an efficient solution the production process. For example, in to all the problems described above. the software production, we may identify We think that the improvement of docu- the following roles: secretary, support ments quality and productivity goes with manager, project manager, programmer, methodological support for organization analyst, sales manager, system engi- of documentation, standardization and re- neer, etc. With roles are related activi- use of documents, automatic generation ties, responsibilities and ability to per- of documents, archiving capacities and form actions to access (more or less maintenance help. "confidential") information. The different roles in a company are identified by the For doing so, TWIST will provide some method used for the production. Obvious- functionalities that could be classified in ly, roles are played by physical persons \ three large classes: named actors. - those dealing with the organization of the documentation A documcnt is an organized set of text, - those dealing with the management of graphics, formulae, etc. For TWIST, doc- the documentation of a specific project uments are structured and constituted of - those dealing with the manipulation of three types of information: the structure, content of documents the presentation and the content of the document. The content is updated by the Each of these functionalities corresponds user while editing the document. The to the need of a particular role within a structure and the presentation corre- company or a project. Each of the specific spond to a standardization of the docu- roles allows the definition o( an environ- ment. ment in which concerned functionalities .3 will be implemented by tools. project documentation. Unlike documentation models, project documentations have a content: the docu- 3.1 Management of documenta- ments realized during the project life cy- tion OI'ganization cle. Documents belonging to a library may be included in a project documenta- Design of the organization of a documen- tion. On the opposite, documents belong- tation consists in combining documents ing to a project documentation may be in sets, describing all the relationships stored in a library. between these sets, defining standards When created (see section 3.1.3), docu- of presentation and structure for the doc- ments may be archived or moved from a uments contained in these sets, and as- set of docnments to another one. These sociating a list of roles with their rights manipulations me also available for sets on each set. of documents. TWIST provides the possibility to de- Otherwise, TWIST allows automatic scribe several structures of documenta- generation of a document providing that tion. These suuctures will be used as its content has been desclibed. models for documentation of projects: All the manipulations described in this each time a project starts, the best section me generally performed by the re- adapted structLU'e of documentation is sponsible of documentation within a chosen, and then duplicated. A project project, and grouped in an environment documelltatioll can therefore be consid- named document manager environment. ered as an instance of a model documell- tatioll Documentation models manipulations 3.3 Management of documents' and creation of instances for projects are content and versions attributed to the same role (for example, the method engineer) and grouped in an As soon as a project documentation has environment named administrator envi- been defined, one can create documents. ronment. Creation, destmction, and consultation of documents are obviously realized using an editor. Nevertheless, TWIST provides 3.2 Management of a specific new functionalities concerning co-author- project documentation ing, information sharing and inter-docu- ment references. These capacities are al- A project documentation is therefore an so supported by the editor. Additional instance of a model of documentation. functionalities concern versions of docu- This instance may be particularized to fit ments (listing versions, purging ver- special constraints bound to the project . sions), and impression of documents For example, a set of documents defined (printing facilities). in the model may be obsolete for a specif- These manipulations are grouped in an ic project, or a set of documents may environment named writer/reader envi- need a particular presentation for a typi- ronment or editing environment. cal project. TWIST allows this kind of ad- aptation. In this case, the modifications performed are local to the concerned tion. Another way to increase the produc- tivity is in reusing documents existing in 4. How these functional- other documentations. Generally in a company some reference documents Hies meet TWIST objec- could always be used to make new docu- tives ments (for example, contract, quality plan, etc.). This con'esponds to the cul- ture (or experience) of the company. Since we mentioned TWIST objectives in These kinds of documents should be in the introduction of chapter 3, we must free access libraries: one can then import now examine in which way the functional- ( any document desired in his own docu- ities proposed will ensure them. mentation, eventually attributing some 4.1 Methodological support specific properties to it (for example, new roles and access rights). ( The organization of the documentation and the association of role/rights upon 4.4 Automatic generation of docu- each set of documents depend on the ments method used to develop the project. Providing a way to descxibe documenta- Generally in a company, many software tion models, TWIST therefore ensure a environments are used assisting people methodological support for the develop- in their work. Each of these environ- ment of any project. ments manages its own data. For exam- If the scheduling of document production ple, an environment supporting project is not a goal for TWIST, any component management has the data needed to pro- able to perform this capacity can be inte- duce monthly reports. Generally this en- grated to TWIST (in the context of soft- vironment is able to produce these kinds ware factory). of documents. The problem is that the documents produced are not managed by 4.2 Standardization of documents the documentation support environment, l and therefore they are not consulted, We have seen that structure, presenta- printed or archived like the other docu- tion and content of documents can be con- ments of the project. trolled independently. Using TWIST envi- In the context of software factories, ronment, the work of a the author of a where environments or tools are able to document is reduced to writing its con- communicate easily, all the documents tent. That is good way to increase the may reside in the documentation environ- productivity. Moreover the use of the ment. In particular, TWIST is able to gen- same structure and the same presenta- erate documents providing that their tion for all documents of a same set war- structures and presentations are de- rant at least an equal quality of presenta- scribed, and pJincipally their content is tion. specified. Describing the content of a doc- ument consists in providing the paths to 4.3 Reuse of parts of documents find some data in another environment. A TWIST allows information shaJing special mechanism is then able to inter- among documents of a same documenta- pret them, generating the specified docu- ment. find a quality plan concerning real-time applications in the nuclear domain"). 4.5 Editing support These kinds of request may be assumed by TWIST providing that documents are TWIST provides capabilities of: annotated with comments or specific in- - managing the co-authoring, in indicat- formation. ing the part of documents reserved by au- thors TWIST manages infOlmation sharing and - sharing parts of documents. in main- references between documents. It allows t.aining the consistency between the dif- archiving and versions control. ferent documents sharing an information - inter-document referencing. in manag- ing links between parts of documents. These functionalities are not managed by 5. Concepts used to im- the editor: this allows the possibility to plement TWIST integrate to TWIST any editor (providing that it manages structure and presenta- The two main underlying concepts of the tion standards). TWIST implementation are structured edition and hypertext stmctures and ma- 4.6 Archiving capacities nipulations Documents have to be archived in the life cycle of the project. Archiving a document means that this document is considered finished and no more modifiable. 5.1 Structured document edition TWIST allows the definition of an ar- There are two kinds of documents manip- chiving property which will be attached to ulation system based on two document documents. The management of relations models. A possible model consists in de- between archived documents and non-ar- scribing documents as characters flows chived ones is ensured. containing special control characters (line 4.7 Maintenance help jump. page jump, spaces...). Another kind of model consists in taking into account Documentation maintenance help re- the logical stmctures of documents: in- quires at least two capacities: stead of only desclibing their physical - brownsing of the documentation presentations. it describes their organi- - maintaining consistency within the doc- zation in telm of chapters. sections, sub- umentation. sections, titles. etc. The physical repre- sentation is described separately. Using the documentation structure, a us- er may be able to find (more or less easi- We have chosen to use this second ap- ly) a specific infOimation. This action is proach. A document is defined by two ge- more difficult to realize since the expres- neric descriptions: its logical structure, sion of the request is not very precise but its default presentation. These descrip- corresponds to a semantic information tions allow the classification of docu- (for example, request as "I would like to ments in classes. The logical structures are essentially tree structures: nodes are components of the logical structure (chapter, section, etc.), and links represent inclusion rela- tions among nodes (e.g., section I -> sub-section I.1). The structure is de- 5.2.1 Graph scribed using rules. The brows of the doc- A graph is a set of nodes, including links ument is equivalent to a path in the tree. and reference links. For example, G, set The physical presentation is attached to of nodes NI, N2, N3, reference link RLI the logical structure. The presentation is and including link ILl, is a graph defined by a set of 11Iles. It allows the ( definition of multiple views of a same document (e.g., the document is viewed as a whole or as its table of contents). The content of the document is dis- ( patched among its nodes. G 5.2. Hypertext concepts An Hypertext abstract machine (or o: graph " : including link HAM) allows the manipulation of five D : node \.... : reference link types of objects: the type-graph, the type-context, the type-node, the type-in- cluding-link and the type-reference-link. Objects of these types are, respectively, Property: graph, context, node, including link, and All the graphs are disjoint (i.e., two dif- reference link. ferent graph - which have different An object is identified by a name. Each names - cannot include the same node, tinle an object is modified a new version or the same link). of it is created. Each class of object may own at- Use ill TWIST: tributes/values pairs. The amibutes and A project documentation 1Il TWIST is a the values are either imposed or speci- graph. fied by the user (i.e., the user can create all the attributes/values pairs he needs). The manipulations provided by the HAM 5.2.2 Context are creation, destruction, modification of all these objects. A context is a part of a graph. It is a set of nodes, including links and reference We can now described more precisely links. For example C = {Nl, N3, ILl} the different objects introduced below, means that C is a context of the graph G and explained in which way they can be used within TWIST. the first node in the associated pair of nodes. (I.e., if NI belongs to C and ILl relies NI to N2 then ILl and N2 belong to C) G If a link (reference or including) is associ- .. c ated to two nodes belonging to the same . - - - - /.... context, then the link belongs also to the context (i.e., if NI and N2 belong to C and L connects NI to N2 then L belongs o:graph \ :including link to C). If a link (reference or including) belongs o : node \..: reference link to a context then its two associated ():context nodes belong also to the context. (I.e., if 'of L belongs to C and L connects NI to N2 then N I and N2 belong C) If a link (reference or including) is associ- ated to two nodes, and one of the two Property: nodes is destroyed, then the link is also Contexts do not have intersection. There- destroyed. fore, they can be used to create a parti- tion of the graph. Use ill TWIST: Including links in TWIST are used to re- Use ill TWIST: alized documents structures, and refer- A context may have an intersection with ence links are used to realize references another one, particularly a context may between documents or parts of docu- include other contexts. ments. A document (or a set of documents) in TWIST is a context. 5.2.4 Node 5.2.3. Including link, Reference link From the HAM point of view, a node is an atomic object characterized by its con- A link is associated to a single orderly tenl. pair of nodes. It is the only a way to con- nect nodes in a graph. For example the Use ill TWIST: including link IL I, in the graph G I, is as- Within TWIST, the content of a docu- sociated to the (NI, N3) pair. ment is stored in nodes. An including link defines an including re- lation between two objects. A reference link defines a simple relation between the two nodes. 5.2.5 Attribute An attribute is a property bound to an ob- Properties: ject (graph, context, node, including link, An including link and its two associated reference link). This object is character- nodes belong to the contexts including ized by the value of its property. An ob- The hypertext concepts [Con 87] associ- ject may own several (attribute/value) ation is a "plus": it allows a large range pall's. of manipulations among documents and Attributes are not pre-defined one may set of documents. Using HAM concepts create any property desired. [Del 86], [Del 87]" the documentation can be viewed as an hyper-docl/mellt. Use ill TWIST: The shating and reference (among docu- Within TWIST, atu'ibutes are used to ments) functionalities can be easily car- specify special properties. For example, ried out. The functionalities provided for the pair (author/J.Smith) bound to a spe- the administrator and responsible of a ( cific node N3, means that J.Smith is the project documentation users are essen- author of the content of the node N3. tially supported using hypertext mecha- nisms .. 6. Conclusion author/smith G The starting point of our work has been a functional description of TWIST. This first approach assured us that providing the user with an integrated documenta- 0: graph \ : including link tion support is not an utopia. Moreover the concepts carried out are well-known. 0: node \. : reference link The CUITent step consists in specifying ~ : attribute atld designing a storage component based on the HAM concepts, aiming at providing, for September 1989, a proto- type which will support the three environ- 5.3 Summary ments described in this paper. We expect that before the end of 1989, at The two concepts previously described least one project in our company will use concern respectively the two types of ob- TWIST. jects manipulated by TWIST: the docu- We hope that this prototype will be the mcnts, and the set of documents starting point of further investigations (documentation). both in the improvement of the edition functionalities and in the extension of the The structured edition clearly allows an use of hypertext concepts to other stor- easy manipulation of parts of a document, age components within ESF. the definition of any kind of link inside the document. The structured edition concern esscntially the reader/writer user. The edition in TWIST is supported by GRIF [Quint 86], [Quint 87]. References: [Con 87]: J. Conklin. Hypertext: An Introduc- tion and Survey, IEEE Computer, September 1987 [Del 86]: Delisle N. and Schwartz M. - Nep- tune : A hypertext system for CAD applica- tions, Proceedings ACM SIGMOD '86 (Washington D.C., May 28-30, 1986), 132- 142. [Del 87]: Delisle N. and Schwartz M. - Con- texts : A panitioning concept for Hypertext, ACM Transactions on Office Information sys- tems 5,2 (April 1987), 168-186. [Quint 86]: V.Quint, I.Vatton,. GRIF: An In- teractive System for SU'uctured Document Manipulation, Proceedings of the Internation- al Conference, J.C van Vliet, ed., Cambridge University Press 1986 [Quint 87]: V.Quint. Vne approche de l'edition structuree des documents, These d' eta!, Universite scielllifique Technologique et Medicale de Grenoble, Mai 1987