Michel Lanque, Alcatel-Lucent
Context of the problem
Customer Information Systems (documentation and embedded information) at Alcatel-Lucent develops customer documentation for industrial products, i.e., User’s Guides, Installation and Maintenance manuals, etc. Our objective is to help technical writers (System & Development teams, Documentation writing teams) to build operational procedures from the contents of technical specifications. We call here “procedure”1 the formal expression of an atomic operational function of the product. A procedure contains steps of operator actions (or end-user tasks) and data to be taken as inputs, all this being under the control of a Graphical User Interface (GUI).
As these procedures are fundamentally reusable (they can be used and referenced in different kinds of documents, like User’s Guides, Maintenance and Installation Manuals, etc.), they are stored in a Content Management System (CMS) under a standard, easy-to-use, and easy-to-assemble format: XML-DITA.
Therefore, please notice that one of the main elements of our process5 is the idea that technical writers don’t have to know either XML nor DITA. On the contrary, we consider that, as the information already exists within informal, natural-language expressed technical documents, some dedicated and specialized tools should be able to automatically extract and re-format this information instead of forcing technical writers to re-express it by manipulating XML and DITA.
Before writing customer documentation, of course the product itself must be specified, designed, and developed. So, technical documents exist that functionally describe the product. These informal documents (called TRS, for Technical Requirement Specifications in Alcatel-Lucent) are mainly based upon use cases descriptions.2
The problem we focus on in this article addresses automatically detecting the structure of use cases within technical documents and re-expressing these use cases as procedures. An application case of this process detects use cases within Alcatel-Lucent technical specifications (TRS).
The best existing solution to this problem is fully manual: it consists in searching manually the structures of use cases within the technical documents and reorganizing manually these structures in order to write the corresponding procedures.
This solution is not good enough for many reasons:
We propose to recognize automatically the use case structure within a technical document through two main steps:
The detection of the use case structure is made by a dedicated automatic process and is helped by the use of a specific use case ontology.3 This ontology describes the main keywords used to express a use case, the semantics of these keywords, their synonyms and their inter-relationships.
Implementing the solution
The process of building the solution contains the following steps:
Evaluating the solution
The value and the unique benefits of this solution can be summarized as follows:
The advantages of this new solution over the best existing ones can be expressed as follows:
Today, the solution proposed in this paper is part of a global process5 and is already implemented within a prototype of a dedicated tool, whose name is ProcedureModeler (you can see an animated demonstration of the tool at https://www.infomanagementcenter.com/Demo/DemoProcModeler.html).
Pilot projects have been launched with the use of ProcedureModeler, and results of these projects are currently gathered in order to build an assessment. The first results are encouraging and seem to prove that this way of generating XML modules from existing informal technical documents is the good one.
1 Michel Lanque, Philippe Larvet, Procedure Analysis from Technical Documentation Alcatel-Lucent internal document, Villarceaux Center, Nozay (France), 2008
2 UML use cases overview the usage requirements for a system: see for instance http://www.agilemodeling.com/artifacts/useCaseDiagram.htm
3 An ontology can be seen as an “intelligent” dictionary containing logical relationships between its terms. See for instance Tom Gruber’s definition: http://tomgruber.org/writing/ontology-definition-2007.htm
4 For semantic distance, see: Philippe Larvet, Semantic Application Design, Bell Labs Technical Journal, Aug.2008, Volume 13 Issue 2, Pages 75 – 91: http://portal.acm.org/citation.cfm?id=1405607 andhttp://www3.interscience.wiley.com/journal/121376597/abstract?CRETRY=1&SRETRY=0
5 Michel Lanque, Information Development Process, Alcatel-Lucent internal document, Villarceaux Center, Nozay (France), 2008