FROM SYSTEM TO TEXT
Documenting Computer Applications using Genre
Rodney J. Clarke
Department of Information Systems, University of Wollongong, Northfields Avenue, North Wollongong, Australia
Email: rodney_clarke@uow.edu.au
Key words:
systemic functional linguistics, computer documentation, computer literacy, genre
Abstract:
Using a semiotic model of language called Systemic Functional Linguistics, this paper identifies and
describes the function, structure and features of two text patterns or genres, the Taxonomic Report and the
Instructional Procedure, that are commonly employed in computer application and tool documentation. A
familiarity with these and other relevant genres constitutes a significant aspect of computer literacy for
documentation users and producers. These specific genres can be used in isolation to organise the overall
structure of small texts, or they can be used in combination to form a composite structure called a macrogenre. The structure of the so-called Computer Training or CT macrogenre is identified, described and
exemplified. Genre theory suggests that readers who are familiar with particular kinds of texts expect the
specific staging of the appropriate genre or set of genres. Conforming to an appropriate genre or
combinations of genres increases the likelihood of the computer documentation being judged as useful by
the community for which it is written. The identification of specific genres can be useful for writers as well
who would then have templates that could assist then in the process of creating useful documentation.
1.
INTRODUCTION
Despite an enormous increase in knowledge
about and utilisation of computer applications and
tools in organisations, there has not been a
commensurate growth in our understanding about
how to create adequate and appropriate written
documentation for users. Computer documentation
authors must rely upon experience, style guides, and
heuristic rules to guide the kind of specialist
technical writing. Generally discussions about the
usefulness of computer documentation foreground
cognitive and perceptual processes, but “… while
important, such approaches fail to account for the
existence of and human dependence on codes for all
intelligibility” (Saunders 1989, 102). ‘Process
models’ of communication (Fiske 1982) are
dominant in mainstream information systems
practice. As these models focus on the transmission
and reception of data, issues of meaning associated
with human communication and context are
therefore excluded. However, several paradigms
exist within the information systems discipline that
emphasise the pragmatic and semantic aspects of
human communication. Two examples of these
paradigms are Organisational Semiotics (see for
example Liu et al 2001a, 2001b) and Language
Action Perspectives (see for example Goldkuhl et al
eds/ 1999; Schoop and Quix eds/ 2001). Potentially
these can be used to theorise the relationship
between the production and reception of computer
documentation. Arguably in order to able to write
computer documentation that can be understood by
the community of readers, for whom it has been
created, we need to understand the social process by
which computer manuals come to mean.
In this paper, the author uses a semiotic model of
language called Systemic Functional Linguistics
(Halliday 1985, Martin 1992a). It has proved to be
useful in a number of different applications including
workpractice description, and information systems
evolution in organisational contexts (Clarke 2000),
hypertext development, multimedia interface design,
and prototyping (see Clarke 2001 for a review). This
model is used because it provides theory and
methods for identifying reusable communication
patterns in written texts that are associated with
communities. These patterns are called genres and
form a kind of cultural property for communities. As
readers we rely on the existence of genres in order to
make sense of what is written and we expect them to
be present in the texts that we read. In our daily lives
we are surrounded by genres, but we are so familiar
with them that we are hardly aware of there
existence- unless the communication fails in some
way. Knowledge about appropriate genres is an
important part of being literate in a community.
There is considerable evidence that literacy can be
improved when genres are identified, analysed and
explicitly taught or employed. In the Australian
secondary education system, many curricula are
designed with knowledge of the genres that will be
required by particular kinds of students so they can
successfully communicate in their respective fields.
We consider computer documentation from the
point of view of this semiotic model of
communication. The types of language resources that
are used in creating any kind of written texts are
described from the point of view of this theory in §2.
In §3, we demonstrate that this theory is applicable
to the general area of computer documentation.
Interestingly, most common forms of computer
documentation only appear to utilise two genres. The
types, structure, and language features of these
genres are described, and they are identified in
several actual computer manuals for tools with the
same overall purpose (web-authoring systems).
2.
TEXTURE, GENERIC
COHESION AND GENRE
Systemic Functional Linguistics defines the
concept of texture as the collection of all linguistic
resources used to construct texts (Martin 1992a,
381), including those read by users in order to
understand a computing application or tool. Whether
knowingly or not, writers employ texture resources
when writing texts, while readers rely on their
experience of these resources when reading texts.
Three broad categories of texture are recognised.
Intrasentential Resources consist of the structural
resources of Theme and Information, Intersentential
Resources involve those languages resources which
tie a text together to form a cohesive whole, and
Coherence which describes how clauses in a text
relate to the contexts in which they occur. One type
of coherence is called generic coherence and refers
to the appropriateness of a text to its cultural
(institutional and organisational) context. Generic
coherence is realised in a text by means of genre,
which is defined as the overall structure, global
organisation or staging of a text. Examples of
commonly recognised ‘academic’ genre include the
Essay and the Case Study Report - both integral to
academic expression. Substituting these for some
other genre, for example a narrative, would likely
result in a low mark or a hilarious outcome (genre
substitution is a standard tactic employed by
comedians). If we were to substitute an inappropriate
genre in this case, we disrupt generic coherence and
make the text difficult to understand within a given
context.
Certain institutional and organisational contexts
are privileged within a culture. Not surprisingly a
number of genre families have been identified whose
constituent genres- the so-called canonical genreshave proved to be very useful and adaptable in a
variety of different contexts. The factual genre
family is just such an example and includes amongst
its members the REPORT and PROCEDURE genres
amongst others (Martin 1992, 563). As we shall see,
genres can also be combined in various ways to form
larger composite genre structures called macrogenres (Martin 1992b).
3.
CANONICAL GENRES IN
USER MANUALS
An informal analysis of the user manuals for
several web-authoring systems suggested that
variants of the REPORT and PROCEDURE factual
genres, the Taxonomic Report genre and
Instructional Procedure genre, frequently occur in
printed user manuals. The types, genre structure, and
some of the language features of Taxonomic Reports
are described in §3.1 to §3.3 inclusive, while the
structurally simpler Instructional Procedures are
described in §3.4. There are very good reasons for
authors organising their documentation using these
genre.
3.1 Types of Taxonomic Reports
In computer training settings, Taxonomic Reports
function to describe a number of classes of things in
a system of classification. Their function is to report
a state of affairs, a phenomenon, or a complex entity,
and consequently they do not organise information
using a time line, sequence or expected order of
occurrence.
A
reasonably
comprehensive
understanding of a topic is needed prior to
attempting to write a Taxonomic Report. There are
two main kinds of taxonomies: part-whole
taxonomies and type taxonomies.
Part-whole Taxonomies are used to distinguish
between, for example, objects, controls or options
(parts) which relate or belong to a common group
(the whole). A simple example can serve to illustrate
this concept of a Part-whole Taxonomy. When users
first start NetObjects Team Fusion Client Version
3.0 - a collaborative website development
environment - they are presented with a "Welcome
To NetObjects TeamFusion Client" window which
consists of three options organised into two groups.
The first group Create a New Site consists of two
options to create a new site using the Blank Site, or
From AutoSite or Template (*nft). The second group
called Open a Site contains only one option, to Open
an existing Site, see Figure 1a. A Part-whole
Taxonomy is the most appropriate genre to use when
creating a written text description of this feature,
since it is obvious that each option is merely a part
of the whole functionality of this window.
The structure of a Part-whole Taxonomic Report
consists of two stages. The first stage is called the
Classification Stage. The Classification Stage
consists of two elements. The first element is
referred to as the Purpose, which introduces the
taxonomy, followed by a Section Preview element
which serves to introduce the names of each of the
taxonomic parts that will be described latter. The
second stage is called the Types/Parts Stage. For
Part-whole Taxonomic Reports, this stage will
consist of one or more Part elements.
Type Taxonomies are used when the objects,
controls or options being discussed do not have a
part-whole relationship. These types of Taxonomic
Reports are used to set the scene. When users first
see the opening screen for NetObjects Team Fusion,
they will see a set of five buttons in the upper-left
hand corner (Site, Page, Style, Assets and Publish),
see Figure 1b. The only thing that links these options
together is that they access major sets of functions
for web site developers within the TeamFusion
application (and of course they look like buttons). It
is clear that these buttons do not share a part-whole
relationship except at a very abstract level of a
developing web site. An example of a skeleton text
describing the NetObjects Team Fusion View
buttons is provided in Table 1. Note that the staging
used in the Type Taxonomy is exactly the same as
that used in the Part-whole Taxonomic Report. The
only difference being that the Types/Parts Stage
consists of one or more Type elements.
3.2 Generic Structure of Taxonomic
Reports
The structure of a genre is provided using a
directed graph notation developed by the author and
referred to as a genre digraph (Clarke 2000). The
diagram is read from left to right. Genre elements are
shown as circles and arrows indicate the sequence in
which these elements are normally organised. The
triangle on the left of the diagram indicates the
beginning of the genre, while the upside down
triangle on the right hand side of the diagram
indicates the end of the genre.
The generic staging of the Part-whole Taxonomy
and the Type Taxonomy are shown in Figure 2a. The
Classification Stage is shown as a rectangular oval
enclosing the two elements of Purpose and Section
Preview, required in both kinds of taxonomic report.
For a Part-whole Taxonomy, the Types/Part Stage
will consist of one or more Parts elements, shown as
a row of elements in the top half of this stage in
Figure 2a. However, for Type Taxonomies, the
Types/Part Stage will consist of one or more Type
elements, shown as a row of elements in the lower
half of this stage in Figure 2a.
A feature in a computing application could be
documented using one Taxonomic Report or several.
The latter case is shown in Figure 2a by the arrow
pointing back to the beginning of the Classification
Stage. However, one or more Taxonomic Report
genres often precede one or more Instructional
Procedure genres in Computer Training manuals, see
Figure 2b. It is unusual to find an Instructional
Procedure genre occurring in isolation, so much so
that the author has created a ‘synthetic’ macrogenre
that includes one or more instances of both. As a
consequence, the upside down triangle marking the
end of the structure only occurs at the end of the
Instructional Procedure in the so-called Computer
Training macrogenre of Figure 2. Parenthetically,
this macrogenre is referred to as the ‘Computer
Training’ or CT macrogenre because it is not only
found in documentation but also in ‘face-to-face’ (or
spoken language) computer training contexts.
3.3 Language Features of
Taxonomic Reports
As well as being structurally similar, the two
types of taxonomic reports also share similar
language features. Table 1 shows the skeleton of a
text conforming to the Type Taxonomy that
describes the NetObjects TeamFusion Client View
buttons. The Classification Stage involves ‘being
processes’ for example, ‘NetObjects provides a set
buttons...’. The Section Preview must mention,
generally in the order in which the reader will
encounter them, the subsequent Parts or Types. In
Table 1, note that the first view mentioned in the
Section Preview, is the one first discussed in the
Types/Parts Stage. The Types/Parts Stage uses
abstract, generalised participants, for example ‘The
Site button allows users...’. Interestingly, these
buttons are described in left to right order as they
appear on the screen, see Figure 1b. Despite
appearances there is no actual or implied time
sequence between the Parts or Types described. The
apparent ordering is not due to the use of this genre.
Rather it is a consequence of the left-to-right reading
practices that European language users also apply to
pictures (Kress and van Leeuwen 1990) and the
developers of the interface have simply reproduced
this convention when designing the interface! The
themes of each of the Parts or Types relate to the
Section Previews. No new sections are introduced
without them first having been mentioned in the
Section Preview of the Classification Stage. The
description of Types or Parts must use words that
express part-whole or type relationships. For
example, in the clause ‘The right-most button is the
Site button that...’ the word ‘right-most’ indicates
that the view is one of several types rather than being
a part of a larger whole. In other words, there should
be no evident hierarchical or dependency
relationship between these views as described in the
text.
3.4 Instructional Procedures
The Instructional Procedure genre is used to
provide a time or event organised sequence of action
or activity. It consists of a Procedural Aim element
followed by two or more Instructions in the order in
which they should occur. The Procedural Aim
should be kept short and be ‘imperative’, for
example: ‘To change the location of a web page in
an existing web site, perform the following steps:’.
The Instructions should be listed in order, for
example: ‘Select the Site view by clicking the Site
View button’, ‘Select the page to be moved by
clicking on it, a blue outline is shown around the
page to be moved’. ‘Hold the mouse key down and
move the page...’ etc. For this reason simply
providing a written list of the actions to perform in
an Instructional Procedure is no guarantee that a user
will understand what to do. Given that for
applications and tools, the subject of each procedure
is ultimately the manipulation of widgets on a screen,
the spatial dimensions of the interface need to be
considered by providing appropriate screen dumps to
form a visual context for the text.
4.
CONCLUSIONS
The Taxonomic Report and the Instructional
Procedure are two genres that are usually associated
with the type of text resources used in Computer
Training contexts. Computer Documentation authors
use Taxonomic Reports because they will need to
classify and organise the ‘digital world’ according to
the functions provided by these products. They also
use the Instructional Procedure genre because that is
the kind of text structure needed in order to provide
information about time ordering of events or the
sequencing of operations related to these products.
Users are very familiar with these kinds of genre
precisely because these kinds of meanings need to be
conveyed to them about hardware and software
products.
An obvious question emerges about what other
kinds of genre could be used instead of Taxonomic
Reports and the Instructional Procedures. There are
other ways in which the text resources used in
Computer Documentation could be structured. One
possibility is that we could organise training texts
using Narrative or Factual Recount genres, where an
assistant or expert might tell us what they did when
faced with a similar situation. The fact of the matter
is that in order to write convincing texts or to repurpose existing ones, we need to select appropriate
organising structures in which to create or reproduce
them, and we also need to have an appreciation of
the complexity of these resources.
Systemic functional linguistic genre theory
suggests that readers who are familiar with particular
kinds of texts expect the specific staging of the
appropriate genre or set of genres. Conforming to an
appropriate genre or combinations of genres
increases the likelihood of the computer
documentation being judged as useful by the
community for which it is written. The identification
of specific genres can be useful for writers as well
who would then have templates that could assist then
in the process of creating useful documentation.
REFERENCES
Clarke, R. J., 2000, ‘An Information System in its
Organisational Contexts: A Systemic Semiotic
Longitudinal Case Study’ Unpublished PhD
Dissertation, Department of Information Systems,
University of Wollongong
Clarke, R. J., 2001, ‘Studies in Organisational Semiotics:
An Introduction’ Australian Journal of Information
Systems 7 (2) May, in press
Fiske, J., 1982, Introduction to Communication Studies
London: Methuen & Co. Ltd.
Goldkuhl, G.; Lind, M.; Seigerroth, U.; Ågerfalk, P. J.
eds/, 1999, Proceedings of the Fourth International
Workshop- The Language Action Perspective on
Communication Modelling Department of Informatics,
Jönköping International Business School Conference
Proceedings September 1999
Halliday, M. A. K., 1985, An Introduction to Functional
Grammar London: Edward Arnold
Kress, G. and T. van Leeuwen, 1990, Reading Images
ECS806: Sociocultural aspects of language and
education Deakin, Victoria, Australia: Deakin
University Press
Liu, K.; Clarke, R. J.; Andersen, P. B.; Stamper, R. K.
eds/, 2001a, Information, Organisation and
Technology: Studies in Organisation Semiotics
Boston, Dordrecht, London: Kluwer Academic
Publishers
Liu, K.; Clarke, R. J.; Andersen, P. B.; Stamper, R. K.
eds/, 2001b, Coordination and Communication using
Signs: Studies in Organisation Semiotics Boston,
Dordrecht, London: Kluwer Academic Publishers
forthcoming
Martin, J. R., 1992a, English Text: System and Structure
Philadelphia/Amsterdam: John Benjamins Publishing
Company
Martin, J. R., 1992b, ‘Macro-genres: the ecology of the
page’ Department of Linguistics, University of Sydney
mimeo
Saunders, P. M., 1989, ‘Communication, Semiotics and
the Mediating Role of the Technical Writer’
Communicating to the World, IEEE 1989:
International
Professional
Communication
Conference Garden City, New York, 1989, 102-105
Schoop, M.; Quix, C. eds/, 2001, Proceedings of the Fifth
International Workshop on the Language-Action
Perspective on Communication Modeling (LAP2000)
14-16th September 2000
Figure 1: (a) the initial window welcoming users to the NetObjects TeamFusion Client Version 3.0 with new
site creation and existing site opening options; (b) a portion of the main screen of the NetObjects
Team Fusion Client Version 3.0
(a)
(b)
Figure 2: Computer Training (CT) Macro-genre consisting of one or more Taxonomic Reports Genres (a),
followed by one or more Instructional Procedure Genres (b).
(a)
(b)
TP
P1
P2
Pn
C
P
PA
SP
T1
T2
I1
I2
In
Tn
Table 1: Example of a Type Taxonomy: NetObjects TeamFusion View Buttons. Text skeleton appears on the
left with the corresponding generic staging on the right
NetObjects TeamFusion provides a set of buttons in the top-left hand corner of the
Client, enabling users to view the site in different ways.
These views are called Site, Page, Style, Assets and Publish.
Classification Stage
Purpose
Section Previews
The right-most button is the Site button which allows users to view the overall structure
of a site by representing the hierarchical relationship between each page ...
Description of Types
The Page button...
T1
T2
T3
T4
The Style button ....
The Assets button ....
The Publish button...