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