Documentation Integrity for Safety-Critical Applications: The COHERE Project
**** Hidden Message ***** Documentation Integrity for Safety-Critical Applications:The COHERE Project
David G. Novick
EURISCO
4 avenue Edouard Belin
31400 Toulouse, France
+33(0)562173838
novick@onecert.fr
ABSTRACT
A key aspect of the COHERE project involves building an
authoring system for documentation for safety-critical systems.
Following a set of documentation integrity maxims, the
project developed two generations of prototype interfaces
designed to assure consistency of information during
production and revision of manuals.
Keywords
Authoring interface, documentation integrity, consistency
1. INTRODUCTION
This paper reports the progress of the COHERE project, which
aims to build an interface for a documentation authoring
environment that assures integrity in manuals for safety-critical
systems such as aircraft. The paper will review the principles
of consistency that drive the design, and then describe two
generations of prototype interfaces for creating and revising
consistent documentation.
The project’s principal goal is to account for cockpit procedures
during development of systems and their documentation for
future Airbus aircraft. The procedures are documented in the
flight crew operating manual (FCOM), which contains:
Permission to make digital or hard copies of all or part of this work for
personal or classroom use is granted without fee provided that copies
are not made or distributed for profit or commercial advantage. and that
copies bear this notice and the full citation on the first page. To copy
othenvise, to republish, to post on servers, or to redistribute to lists,
requires prior specific permission and/or a fee.
01990 ACM l-!58113-004-W98/0009 $5.00
Joel Juillet
EURISCO
4 avenue Edouard Belin
31400 Toulouse, France
+33(0)562173838
l a set of parameters, such as charts for take-off and landing
speeds as a function of weight,
l a set of explanations of the aircraft’s systems and controls,
such as the hydraulic system and the interface to the
navigation computers,
l a set of procedures, such as for normal, abnormal and
emergency conditions, and
l a set of checklists.
The FCOM is written and published by the a&aft
manufacturer and is often adapted and republished (sometimes
in translation) by individual airlines to meet their own
guidelines or standards for publications and operations. For
example, Singapore Airlines and Virgin Airlines both use
FCOMs directly published by Airbus, with sequence
differences indicating minor specialization of the FCOM for
their particular needs. United Airlines and Lufthansa revise, to
a greater extent, the FCOM and publish their own versions.
Air France revises and translates the FCOM into French in
publishing its own version.
A key aspect in achieving the project’s goal involves the
development of an interface for the system through which
engineers and authors develop and revise future FCOMs, which
are likely to be based on hypertext. This builds on work on
(re)generation of documentation for software and for ahcraft
. In contrast to hypertext systems for specializing a
document for the user , a document development system
faces the issue of making things consistent throughout the
document. An aimraft is a complex system; for example, the
first chapter of the FCOM for the Airbus A340 aimraft
contains 13 pages of definitions of abbreviations, ranging hm
A (Amber) to ZFW (Zero Fuel Weight).
The problems of documentation integrity with respect to
consistency are not simply academic. A review of recent
reports from the National Transportation Safety Board discloses
a number of accidents and incidents arising from different kinds
of inconsistency in documentation. In one case , an aimrat%
maintenance and (non-updated) flight manuals contained
different versions of the procedure for releasing the parking
51
brake. The pilot used one of the versions, which left the brake
unreleased and thus caused the aircraft to nose over on landing.
In another case , the text and accompanying diagram in a
maintenance manual for a commercial jet differed in a way that
led to the failure of a thrust reverser through loss of a cotter
pin. The text indicated that a single washer should be fitted
before a nut at the end of a pivot bolt in the thrust-reverser
linkage; the diagram indicated two washers. Maintenance
personnel followed the diagram rather than .the text. As a
result, the bolt did not extend far enough beyond the nut for a
required cotter pin to be inserted correctly. The loss of the
cotter pin led to loss of the pivot bolt and consequent
malfunction of the thrust reverser. The airline found that other
aircraft of the same type also had missing cotter pins due to the
same cause.
2. INTEGRITY MAXIMS
The project is starting its third year of effort, studying in
particular the FCOM for the Airbus A340 aircraft. To date, the
project has included (1) a comprehensive comparative review of
the original A340 FCOM produced by Airbus Industrie and
editions based on this FCOM produced by airlines in France
and Germany, (2) situated task analysis with Airbus and
Aerospatiale staff who designed the development and revision
process and who actually produce and revise the FCOM, and
(3) interviews with airline staff who adapt the Airbus FCOM
for their own company and provide feedback to Airbus on
FCOM use.
We interviewed technical support engineers, development
process managers, technical documentation managers and
specialists, and publications managers and staff. Our study
revealed a need to support development and revision across
organizational boundaries. In particular, as the FCOM (and the
systems it documents) is developed, revised and adapted,
information is transferred back and forth between Aerospatiale,
Airbus Industrie, and the airlines. The flow of information is
not linear, in that there are major feedback loops between
Aerospatiale and Airbus, and between Airbus and the airlines.
There is a meticulous process of technical validation among all
the participants.
The project’s reviews and interviews enabled us to develop a set
of maxims for consistency in safety-critical documentation:
Coherence of meaning: Integrity of semantic relationships
Ml Semantic relations should not be changed unless the
change is intended
Coherence of reference: Integrity of consistency and
differentiation in referring to domain entities, actions and
relations
M2 References to the same thing should appear the same.
M3 References to different things should appear different.
Corollary:
Cl Changes in referential expressions should be
propagated.
The word “integrity” as used in the maxims has at least two
meanings, which play complementary roles. Documentation
can be said to have integrity when all of it is present in the
form intended by the authors. Documentation can also be said
to have integrity when the user can believe it without
reservation. Thus documentation with integrity remains
coherent through development and revision, and can be trusted
in use. And, even if FCOMs could be generated from
specifications [lo, 111, the developers must still ensure
integrity across an iterative or co-evolutionary process.
The maxims are consistent with findings of other
documentation researchers who conducted task analyses of
similar situations, particularly with respect to support for
accurate and consistent terminology and for propagation of
changes .
Other researchers have begun to investigate methods of
automatically generating documentation content from a model
of the system to be documented. In particular, the DiDoLog
prototype showed that a partial model of a system, such as
that of an aircraft brake system, could be used to generate a
textual description guaranteed to be consistent and complete
with respect to the partial model. However, they did not
discuss the generation of procedures and, especially, did not
address the question of how to maintain the correctness and
completeness of the information after generation of the raw
text, such as in the transformation of the raw text into a more
comprehensible form and possible subsequent revision or
adaptation as in the case of the Airbus FCOM.
An approach to the automated generation of text for procedures
was developed by Paris et al. , who created a tool calIed
DRAFTER for the generation of instructions in multiple
languages. Using a knowledge editor, the author creates an
abstract, language-independent representation of the underlying
system, including the steps to be taken by the user. From this
specification, DRAFTER could produce instructions in both
French and English. If the author wished to revise the text,
they would change the specification and regenerate the text.
DRAFTER’s underlying representation was object-oriented, in
that it employed classes and instances. Its language-generation
facilities were sophisticated. The creators of DRAFTER did not
explicitly address the issue of specialization of documentation
within and across organizational boundaries. However, it is
clear that their approach could be adapted to this application.
The completely model-based approach of DiDoLog and
DRAFTER, though, meant that authors faced a choice between
hand-tuning of text or losing any guarantees of consistency. In
52
other words, the text of any part of the documentation had to
be completely regenerated from the model, so any changes
made in the text itself would necessarily be lost. Moreover,
model-based specifications can be difficult for authors to
interpret and modify . A contrasting approach to would be to
use a structure editor, where the author enters text that has,
within it, known relations among the text entities. The
structure-editor approach would enable hand-entry and handtuning
of text, and could preserve semantic relations to the
extent that these were representable in the sn-uctures of the
grammar used. Moreover, coherence of reference could be
produced through entry of references to objects rather than
through entry of the text itself. In other words, the object
would generate its own referring expression-and thus
guarantee consistency, in a manner similar to that employed in
DRAFTER-while surrounded by non-object-based text.
Indeed, this approach could produce coherence of reference even
if the text (other that the objects themselves) were entirely freeform.
3. INTERFACE PROTOTYPES
The main question we faced was how to develop an authoring
system that would embody the maxims in the informationsharing
organizational context of FCOM development. Indeed
the eventual system would have to meet the consistency
criteria and support sharing and revision across organizations.
Early design choices included an object-oriented architecture as
a basis for generating consistent language, and hypertext
capabilities for both the editing and revision process as well as
possible future deployment of electronic FCOMs on board
aircraft. Accordingly, we named our system the Common
Object-oriented Hypertext Editing and Revision Environment
(COHERE). The word “common” can be understood in two
complementary senses: as common across organizations and as
common between text and graphics, which typically were
produced separately for current-generation FCOMs.
Using the results of (a) an extensive analysis of key sections of
the Airbus, Air France and Lufthansa FCOMs and (b) the
interviews, we created two generations of prototype interfaces,
the first conceptual and the second functional . The
prototypes demonstrated how the consistency maxims could be
embodied in an authoring system intended for distributed use.
The conceptual prototype explored the design space of the
authoring system; the functional prototype indicated the
technological possibilities and constraints of realizing key
points of the conceptual prototype in an operational setting.
Together, they suggest some of the possibilities and
limitations encountered in developing tools for supporting
authors of documentation in ways that preserve meaning across
the document and through revision.
3.1. Conceptual Prototype
The conceptual prototype was developed in HyperCard. The
prototype presents a small part of the contents of the A340
FCOM as a user might see the documentation if it were
presented in hard-copy form. The concept prototype can be
considered as a partial structure editor, as it encompasses some
basic concepts such as (a) central, common definition and
reference of key terms and (b) grammar-based definition of
documentation structures. The prototype contains lexica for
domain objects (like “flight level”), actions (like “select”) and
relational expressions (like “and”). Each lexicon has buttons
that enable access to the specific definition of a term or
instances of a term in the text. Figure 1 shows a page of the
prototype manual, in “use” (as opposed to “authoring”) mode,
with hyperlinks highlighted due to presence of the cursor in the
text field. In the conceptual prototype, we attempted to
reproduce as much as possible the look of the actual Airbus
FCOM in order to connect the new concepts to something
familiar to the technical support staff.
The prototype demonstrated authoring techniques, including the
ability to refer to domain terms as objects rather than flat text,
the ability systematically to characterize formatting of pieces
of the documentation that play different roles (such as “notes”),
and the ability to define and use formal languages to describe
and control the structure of the document (e.g., a “procedure”
consists of one or more “checklists”). Document structures
were shown as defined through a composable, recursive
language.
As true objects were not available in HyperCard, the definitions
of the key terms in the lexica had the appearance rather than
functions of objects. This means that, for example, insertion
of a reference into the text actually inserted text (albeit marked
text) rather than an actual object reference.
Similarly, the prototype relied on link-simulating techniques
that provided the appearance of hyperlinks through search rather
than through pointing. This meant that, for instance, the
prototype’s implementation would not be extensible because
the “linking” is affected by the order of the definitions in the
lexicon’s stack; moreover, an object and an action or logical
operator could not have the same textual representation. The
“authoring” and “use” modes actually did insert the target term
in the text, but the new term was “linked” in the same manner
as the others.
Finally, the indexes for function-formatting and slructuredefining
did work, but their actual operation remained
unimplemented. In general, the concept prototype could be
considered as a partial structure editor. That is, a full slructureeditor
would enable creation of content only through, for
example, grammar-based mechanisms such as cascading
menus.
53
FMGS PROCEDURE
CRUISE
4.05.50 P 1
REV02 SEQOOl
1 REACHING CRUISE FLIGHT LEVEL]
- When reaching the intended initial CR2 FL :
l C! that adisplays ALT CR2 inthend column which ensures CRZ MACH,
predictions validity aa well as, SOFT ALT mode engagement.
- g the fidoes r&display ALT CRZ at thexgned 5 (due to ATCorder):
l
I(
PROG m........... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..DEPRESS
l ENTER the current CRZ FL
TYPICAL mFM- A IN CRUISE
- If the end of the CLIMB Dhase has been achieved with SELECTED MACH and ECON MACH
is planned for the cruise, a messaqe “SET MANAGED SPEED” is displayedon the PFD
(FMA) and a messaqe “SET SPEED AUTO” is displayed on the MCDU.
l FCU SPD selector knob . . . . . _ . . . . . . . . . PUSH
Figure I. Example page from conceptual prototype
While the concept prototype was not entirely structure-based, it
did encompass some basic concepts such as (a) central,
common definition and reference of key terms and (b) grammarbased
definition of documentation structures. It demons-ted,
nonetheless, that a digital, hypertext-based documentation
system can provide links to author-users that enable the authorusers
directly to determine the definition and source of any
term. In particular, it showed that the system can provide
lexica of terms, technical or otherwise, used in the FCOM.
The conceptual prototype’s lexica contained objects (domain
objects like “flight level” rather than computer-language
objects”), actions (like “push”), and relational expressions (like
“and”). The prototype had a lexicon of 26 domain objects,
seven actions (such as “compare” and “depress”), and five
relational expressions (such as “and” and “if’). Figure 2 depicts
the lexicon page for domain objects. The object CRZ MACH
is highlighted, indicating that this was the last object selected.
The radio buttons Use and View determined whether selection
of an object would display its definition or insert it in the
document being authored. Figure 3 shows the definition of
CRZ MACH linked from the Object Index. The object’s name
is for internal use, so the “full” version of object’s
representation need not be identical to its name.
3.2. Functional Prototype
The conceptual prototype had a number of limitations. Because
it was built in HyperCard, true objects were not available and
text-linking, although functional, was simulated. To explore
implementation issues, a new, functional prototype of the
interface was developed in Java, which provided true objects
and hypertext. Figure 4 depicts, in schematic form, the main
parts of the interface.
54
11 I~l~Jet:lr 11 Actions II logic II
I=)
(I)I!IPte)
Figure 2. Domain-object lexicon
The core of the functional prototype consisted two side-by-side
windows, which (1) supported text entry and automated
insertion of object-instances and (2) displayed the generated
text. The document was represented internally in SGML, with
references to an object Iibrary for domain objects, actions and
relations. The prototype also supported definition of new
objects and generation of HTML documents from the SGML
11 Objects 11 Actions 11 logic 11
Object (Done) (T)(Show)
1 cruise speed I
Short name
@ 1 Cruise Mach
Abbreviation
0 [CR’ MACH
Definition
1 the speed selected for the cruise phese of u
the flight.
I I 1 tq
[Show Revisions)
Figure 3. Domain-object definition
source files. The HTML documents represented editions of the
target manual, and supported interaction via Web browsers.
The author’s main focus of activity with the system would be
through the text-entry window, where free text and objects were
combined. The functional prototype focused on the engineering
problems of creating and entering the objects, producing true,
Proposed text
completion L 1 navigation
The CD-OBJ N=17 (descent) F=as> CDOBJ
N=18 (mode) F=fs> is CD-OBJ
N=19 (disengage) F=p> by one of the
following CD-OBJ N=20 (condition)
F=fp>: <BR>
-loss of the nal
\ Entry Window
The DES mode is disengaged by one
of the following conditions:
- loss of the na
\ Generated Window
Figure 4. Schematic overview offunctional prototype
55
dynamic hypertext, and generating both SGML and HTML
representations. Consequently, some ideas developed in the
conceptual prototype, such as text structures and types, were
not explored in the functional prototype.
In the text-entry window, entities were represented as SGMLtagged
instances. When text was being entered in the editing
window, the prototype would dynamically suggest textcompletion
of known objects, actions and relations in a text
field in the window’s upper border. Pressing the “control” key
caused the system to replace the currently typed prefix with the
SGML-tagged instance proposed as a completion, with the user
selecting characteristics for the instance (such as number and
abbreviation) from a pop-up dialogue box. In this way, for
example, a reference to the object <AIRPORT> could generate
“airport,” “airports, ” “APT” or “APTs.” Along similar lines,
the prototype provided different syntactic forms for actions that
could be specified by the user. The prototype had
complementary representations for all entities in both English
and French.
In the generated-text window, entities were represented by
referring expressions generated by the instance. These
expressions appeared as colored, clickable text. Clicking on
one of these links caused the prototype to display the instance
definition in a pop-up window. The scan of the source SGML
was rather slow, so the generated-text window was re&shed on
explicit command of the user rather than automatically, which
would have caused annoying delays.
When the author wished to enter a new reference for which an
object was not already defined, he or she could create new
objects. For each object, the prototype provided a dialogue box
with appropriate buttons and text fields to enable the user to
enter slot values; among the slots were parallel fields for entry
of English and French versions of the same entities, so that a
single common object could be used to create documents in
more than one language and so that translation of the FCOM
between English and French (in either direction) could be
partially automated. This was not as sophisticated as the
support provided by DRAFTER [7, 81 but neither was it as
restrictive.
When a document was complete, the author could export the
underlying SGML as an HTML file that represented the
“finished” manual page. The HTML file contained the author’s
ffee text plus, embedded where specified, textual referen=
generated by the objects that were marked as hyperliuks to the
reference’s definition in an auxiliary HTML file.
The prototype had several limitations. These included lack of
handlers for graphics and lack of formatting. Despite these
limitations, however, the prototype did demonstrate the
creation and editing of hypertext documents using a common
store of objects to deride consistent referring expressions.
SGML files were automatically created via authoring actions in
the text-entry window, HTML files were automatically created
from the SGML files, and the auxiliary HTML files were
created that contained the definitions of the objects that were
linked from the HTML manual pages.
4. DISCUSSION
The work presented here led to the development of a functional
specification of the COHERE system. In creating the
specification, we learned a number of lessons in postimplementation
analysis of the prototypes. Among these was
that the internal representation of objects should be changed to
rely on type information rather than on instance. Moreover, the
functional specification left some issues unaddressed. First,
there was no enforcement of use of objects for reference; the
author could reject the system’s suggestion or could create new
referential expressions without creating new objects. Second,
there was no assistance for checking whether a new object
duplicated an existing object in all but name, Third, there was
no automated method for assuring that the generated references
were all distinct. This means that while the system as currently
designed provides otherwise unavailable assistance authors in
adhering to the consistency maxims, the burden of checking
consistency when creating or modifying objects remains with
the author. We plan to address these issues in future work.
The utility of the structure-editor approach presented in the
conceptual prototype can be inferred from recent results in the
DRAFIER project. A second-generation system involved
creation of an implicit system model through the use of
cascading menus . It is an open issue whether the approach
of model-and-generate, either through explicit or implicit
models, is feasible for large industrial projects. COHERE’s
relatively light-weight approach may provide sufficient support
for the consistency maxims while not requiring a massive
system-modeling effort.
5. ACKNOWLEDGMENTS
This work was supported by a research contract from
Aerospatiale Aeronautique. Sdid Taxi, Marc Nanard and
Jocelyne Nanard provided interaction and advice. Airbus
Industrie, Air France and Lufthansa provided important
assistance to the project.
Joel Juillet’s current address is Etat Major de la Marine,
Division Aeronautique Navale, 2 rue Royale, 00300 Arm&,
France.
6. REFERENCES
1. Barth, H. (1997). DiDoLog-A system for developing and
automatically generating guaranteed consistent arkl
complete user manuals for interactive systems, RVSDemo-
O 1, http: //www.rvs.uni-bielefeld.de/-ihbarth/
DiDoLog.html, 14 April 1997
56
2. Budde, R., Kautz, K., Kuhlenkamp, K., and Ziillighoven,
H. (1992). Prototyping: An approach to evolutionary
system development. Berlin: Springer-Verlag.
3. Johnson, W.L. (1994). Dynamic (re)generation of software
documentation, Proceedings of the Fourth Systems
Reengineer@ Technology Workshop, APL Research
Center Report RMI-94-003, Johns Hopkins University
Applied Physics Laboratory, 57-66.
4. Johnson, W.L. and Erdem, A. (1995). Interactive
Explanation of Software Systems, Proceedings of the
Knowledge Based Software Engineering Conference,
5. NTSB (1996). Docket CHI96LAOll.
6. NTSB (1994). Docket LAX94LA137.
7. Paris, C., Vander Linden, K., Fischer, M., Hartley, A.,
Pemberton, L., Power, R., and Scott, D. (1995). A support
tool for writing multilingual instructions. Information
Technology Research Institute Technical Report No. ITRI-
95-11.
8. Paris, C., and Hartley, A. (1996). Multilingual document
production from support for translating to support for
authoring. Information Technology Research Institute
Technical Report No. ITRI-96-17.
9. Power, R., Scott, D., and Evans, R. What you see is what
you meant: Direct knowledge editing with natural language
feedback. Information Technology Research Institute
Technical Report No. ITRI-97-03, 1997.
10. Thimbleby, H. (1996). Creating user manuals for use in
collaborative design, CHI 96 Conference Companion, 279-
280.
11. Thimbleby, H., and Ladkin, P. (1995). A proper
explanation when you need one. Proceedings of the BCS
Conference on Human Computer Interaction, Huddersfield,
UK. Cambridge: Cambridge University Press.
57
页:
[1]