Design Rationale for Complex System Documentation

Saïd Tazi, LIS, Universite de Toulouse 1
David G. Novick, Eurisco


Documentation of a complex system like an aircraft requires a model that enables tracing of decisions made by the author(s). The authors need to be able to include not only the information content deriving from the design but also communicative intentions-the traces of various design choices by the designers and the authors. In this paper, we suggest an authoring model capable of incorporating different kinds of knowledge in an authoring environment for technical documentation. The model is based on the idea of discourse acts and enables representation of intentions in addition to the domain content. We show how this model can be used in the case of documentation of procedures for commercial aircraft.

Keywords: Technical documentation, traceability, design rationale, speech acts, domain acts, meta acts


La documentation d'un système complexe comme un avion a besoin d'une modélisation qui puisse garder les traces des décisions prises par les auteurs. Il est nécessaire de donner aux auteurs la possibilité d'y intégrer non seulement le contenu informationnel selon les spécifications des concepteurs, mais aussi les intentions de communication, les traces des différents choix de décision des concepteurs et des auteurs. Dans cet article nous proposons une modélisation de l'activité de rédaction pour pouvoir incorporer différents types de connaissances dans un système d'aide à la rédaction de la documentation technique. Ce modèle est basé sur la théorie des actes de discours, il permet de représenter aussi bien les intentions que le contenu propositionnel. Nous montrons comment ce modèle peut être utilisé dans la cadre de la documentation des procédures de pilotages d'avion civils.

Mots Clés: Documentation technique, traçabilité, logique de conception, actes de discours, acte du domaine, méta acte.


The design of complex systems such as commercial aircraft continually evolves in response to technological advances and changing needs. The documentation for these systems thus requires a model that facilitates a corresponding evolution. Moreover, documentation associated with a complex system typically is employed in multiple contexts, such as design, maintenance and training, while the documentation is usually developed only for the "use" context, which in some circumstances is safety-critical. As a result, documentation is subject to a tension between (a) the necessity for the documentation to evolve along with systems and (b) the need to target the documentation to meet precise, often critical objectives.

In addressing this tension, traditional documentation suffers from a linearity syndrome. That is, writing uses a channel that permits expression of information in a sequential, linear way, but where the information expressed arises out of knowledge that can be represented as a network containing multiple types of knowledge about the domain, about goals and intentions, and even about ways of communicating. The linearity syndrome results in multiple cases of ambiguity. The goal of the work presented in this paper, then, is to develop a formalism that enables modeling the process of written communication so as to address the linearity syndrome. We suggest that authors can be provided with the means to justify their decision in the design and development of documentation.

The Design Rationale of Artifacts and their Documentation

The logic of a design, which collects the reasoning used during the design process, is commonly referred to as the design rationale (DR). This involves keeping track of design decisions for an artifact, using conceptual, notational or methodological tools. There are a number of reasons why it is advantageous to record the design process in terms of DR. First, it improves communication among members of the design team (Conklin, 1991). In effect, one can view records of design decision paths as a means of communication among a group of designers, especially when they are geographically or temporally distributed. Second, it enables structuring the design process in an effective way, helping to avoid contradictory or otherwise inconsistent choices. Third, DR can be used to facilitate maintenance of the artifact because the availability of information about reasons for design choices often makes revision easier. Fourth and most important, the advantage of DR is that the record of design decisions can be used in the design of future versions or extensions of the artifact. In short, DR can be viewed as a kind of organizational memory for know-how.

Documentation of a system follows the same life cycle as for a system itself: it is specified, designed, produced, distributed and then maintained. In the case of documentation for complex systems, use of DR for documentation becomes even more important, because of the quantities and qualities of information, the correspondingly complex structure of the document, the multiplicity of intended users and uses, and the relatively large number of people (such as engineers, technical writers, editors, graphics specialists, and formatters) who are involved in the documentation's production.

In the literature, DR is described as a set of semi-formal tools, often graphically based. The best-known notation is QOC (questions-options-criteria) (MacLean et al., 1991), but gIBIS (Conklin & Begeman, 1989) and DRL (Lee & Lai, 1991) are also widely known. As in the case of DR for systems, DR for documentation has multiple advantages, including improvement of communication among the members of the authoring team, and among revisers and authors. Moreover, DR for documentation would enable authors to create another kind of document structure, which we will call the intentional structure, that characterizes the document in terms of communicative goals. DR for documentation would also facilitate revision. Finally, if propagated into the disseminated document, DR for documentation could have a significant impact on readers, who could gain a more complete understanding of the document's information through access to the DR. The artifact's own DR could be used during development of the documentation to provide rationale with respect to domain content.

Our research disclosed a case where an authoring team for a complex system used the features of a word-processing program to provide a simple means of tracking DR for their documentation. Members of the team explained that they used Word's annotation feature to communicate with others in the group about questions they faced and explanation of design choices they made. While not entirely systematic, this effort clearly provided a useful function in the authors' context, which involved preparation and revision of multi-volume operating manuals for an extremely complex artifact. In this case, the annotation feature linked the DR to the textual (or graphical) element but did not (1) formally express the authors' acts and their relationship to the elements or (2) provide access by end-user readers to the DR.

Using Discourse Acts to Model DR for Documentation

To make DR for documentation more powerful and useful, we propose a representation based on discourse acts. Our idea is to clear away constraints imposed by the implementation of the interface to the DR support system, which can be a serious impediment to use. As the overall problem involves communication among the members of the authoring team, we favor a representation that explicitly addresses communication, namely an adaptation of speech-act theory (Searle, 1969).

In order to be able to record authors' decisions about writing and production, we distinguish two complementary types of discourse act. The first kind of act involves the effect that the author wants to produce with respect to domain concepts; the second kind of act involves effects that can be considered independent of domain. This distinction lets us discern two corresponding kinds of acts in writing, which we call domain acts and meta acts. Domain acts, for example, involve teaching the reader something about the domain or inducing the reader to take some action such as executing a cockpit procedure. In contrast, meta acts express the author's intentions with respect to the document itself, such as choice of style.

Meta Acts

Characterization of communication through a written medium depends on a number of factors, including the nature of the medium (such as software, paper or white board) and the author's level of expertise as a writer. In this paper, we focus on writing using software tools for text, and we assume that the author is an expert with respect to both the tools and the domain. In general, though, these factors can be divided into three categories:

  1. Factors dealing with the physical appearance of the document, such as the typography and other matters involving formatting. For example, a formatting factor might involve a decision to use multiple columns per page.
  2. Factors dealing with the logical structure of the document. For example, such a factor might involve the organization of a document into sequential sections.
  3. Factors dealing the expressive style of the document. For example, such a factor might involve a choice of whether to use text or graphics to express some information.

These factors are generally used consciously by the author to effectuate a strategy of maximizing the document's communicative effectiveness and minimizing the reader's mental load. But sometimes these choices are not always explicit. Consequently, they constitute a communicative intention that, through noting choice of category or factor, can be recorded in a document's DR. Our study of industrial operating manuals for aircraft indicates that there are at least three classes of DR that can be described through meta acts: DR for formatting, DR for organization, and DR for revision.

DR for Formatting

Despite enormous improvements in the field of publishing arising out of information technology, and despite the specification of various standards, the meaning of the use of editing, typographic and formatting conventions remains implicit, and so these can still give rise to many ambiguities. For instance, the use of italic characters can mean emphasis, a definition, a foreign expression, or something else entirely. To represent these meanings, authors can use formatting meta acts to record the reasoning that led to the particular design choices made. So an author would take and record a meta act of formatting rather than simply entering text in italics or between quotation marks, for example. Meta acts for formatting, then, are verbs that apply to the typography or other physical characteristics of the presentation of the document, with the first argument representing the style to be applied and the second argument the object of the verb. Such meta acts would be something like these examples:

EMPHASIZE(<presentation_style>, <term>)
USE_FOREIGN_PHRASE(<presentation_style>, <foreign_phrase>)

DR for Organization

Hayes and Flower (1980) identified document planning as a distinct process. In our view, authors use organization meta acts, more or less explicitly, in creating the logical structure of their documents, and these acts can be applied recursively. In DR for documentation, representation of this process in terms of meta acts can help authors avoid some types of inconsistencies or ambiguities in document structure. One example of the kind of ambiguity we seek to eliminate involves the unusual use of carriage returns. In many (if not most) document preparation system, a carriage return indicates the end of a paragraph rather than the end of a line, contrary to many people's expectations. Likewise, many document preparation systems do not check the consistency of new headings, whether these are hierarchically at the same or different levels. For example, it is generally considered difficult to justify the use of a lone heading at a given level. Examples of document organization meta acts include:

ENTITLE_TEXT(<title>, <titled_text>)
DIVIDE_TEXT_ELTS(<chapt | sect | para>, <seq_of_text_elts>)
DEFINE_OBJ(<object>, <definition>)
ILLUSTRATE_OBJ(<object>, <illustration>)
LIST_OBJS(<list_mark>, <seq_of_objs>)
ENUMERATE_OBJS(<numbering_mark>, <seq_of_objs>)

DR for Revision

Revision is an indispensable part of the process of writing and thus is a necessary part of the representation of DR for documentation. In particular, authors typically correct, add or delete text. If an author wants to keep track of these revisions, he or she should have recourse to a system for maintaining their trace across succeeding versions. Here, we focus particularly on enabling tracing of the reasons for revisions. This is another instance where meta acts can be used. Meta acts for document revision comprise not only the verb indicating the nature of the act, like INSERT or DELETE, but also the trace of the explanation for the revision. Examples of revision meta acts include:

DELETE(<text>, <place>, <explanation>)
INSERT(<text>, <place>, <explanation>)

We note that analogous acts could apply to the organization of a document as well as to its textual content.

Domain Acts

This second aspect of our documentation process model describes the effects that the author intends to take with respect to changing the mental state of the reader. These intended effects are normally that the reader believes something or that the reader takes some action, which is often the purpose of documentation for aircraft flight decks. All of these effects concern concepts and actions at the domain level. In our study, we looked at documentation for commercial aircraft. The flight crew's definitive documentation is a large manual called the flight crew operating manual (FCOM). The domain acts found in FCOMs are overwhelmingly of two types: INFORM and DO. The INFORM acts largely carry out the FCOM's descriptive function, informing and reminding the crew about aspects of the aircraft. The DO acts appear as part of the FCOM's prescriptive function, indicating to the crew that they should perform particular actions in given circumstances.

Some other domain acts found in FCOMs include:

The crew chooses one of a number of available operating modes, such as lateral mode and vertical mode.
In some situations, an FCOM will warn the crew about the consequences of a condition or action that have safety considerations.
The crew verifies a state or value before proceeding to another action or phase.


This paper has set out reasons why the approach of design rationale should be extended from systems to their associated documentation, particularly in the case of complex systems. As documentation adapts to developments in the system and to differences among users, systematic storage, access and use of DR as part of the documentation can assist authors in producing the effects they intend.

Readers who have followed our argument this far may have formed an impression that we favor a "formalist" approach to authoring. We suggest, in fact, that the semi-formal representations typically used in DR systems should be elaborated to encompass formal representations of domain and meta acts for authoring documentation for complex systems, especially where there are safety considerations. The authoring environment for a team creating documentation for safety-critical systems should be clearer and more precise than a word processor used for, say, the preparation of a routine business letter or for writing a short story. Ideally, the power of common formal representations should enable the validation of the underlying system, the verification of the documentation with respect to that system, the validation of the documentation with respect to its intended users, and the verification of the documentation with respect to consistency.

At this point, our research permits us to claim that we have identified instances and classes of authoring acts in the FCOM domain. To the extent that DR is represented using the formalisms we developed here, the store of acts should be naturally expanded as the pragmatic needs of authors and readers are incrementally addressed. We expect to continue to identify instances of different acts as our research progresses, and hope that other researchers in the field will contribute to the creation of a more general store of knowledge along these lines.


Conklin J., and Begeman M.L. (1989). gIBIS: A tool for all reasons. Journal of the American Society for Information Science, May 1989, 200-213.

Conklin, E.J. and Yakemovic, KC.B. (1991). A Process-Oriented Approach to Design Rationale. Human-Computer Interaction, 6, 357-391.

Hayes, J. R., and Flower, L. S. (1980). Identifying the organisation of writing processes. In L. Gregg, and E. R. Steinberg (eds.), Cognitive processes in writing. Hillsdale, N.J.: Erlbaum, 17-35.

Lee, J. and Lai, K-Y. (1991). What's in Design Rationale? Human-Computer Interaction, 6, 251-280.

MacLean A., Young R.M., Belloti V., and Moran T. (1991). Questions, Options and Criteria: elements of design space analysis. Human-Computer Interaction, 6, 201-250.

Searle, J. (1969). Speech acts. Cambridge: Cambridge University Press.

This paper was published as: Tazi, S., and Novick, D. (in press). Design rationale for complex system documentation, Proceedings of the Conference on Complex Systems, Intelligent Systems and & Interfaces (Nimes 98), Nimes, FR, May, 1998, Lettres de l'Intelligence Artificielle, combined volumes 134-236, 49-51.

DGN, April 6, 1998
Valid HTML 4.0!