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:
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 macro-genre. 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 genres- have 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 macro-genres (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.