Our Articles ...
On Complex Documentation
On Complex Documentation
|How Electronic Outlining Can Help You Create Online
(Talk given at 15th Annual International
Conference on Computer Documentation, October 19-22, 1997, Salt Lake City, Utah.
Association of Computing Machinery (ACM), Special Interest Group on Systems Documentation
(SIGDOC). Final version available in Conference Proceedings, 211-221.)
Ugh. Outlines. The very thought makes many writers shudder. I understand the revulsion. As taught in high school and college, the paper outline often seemed an arbitrary chore, a rigid plan we had to follow even if we came up with a better idea later, a stupid rigamarole of labels and formats from Latin and math. Why did our teachers assign them so often?
Well, because our papers were, structurally, a mess. Our teachers hoped that in the process of outlining we would consider various possible structures, and emerge with the most coherent, effective, and convincing organization possible. Alas, most of us just wrote the paper and then cooked up a fake outline to get by. We neatly avoided getting any benefit out of all those outlines.
Ten years ago, with the invention of electronic outlining, the world received a tool that actually made it possible to get that benefit out of outlining. The electronic outliner made it easy to create and revise an intellectual structure, analyzing the hierarchy and sequence more rigorously than ever before, then carrying out more than a dozen structuring activities. But, given the worlds prejudice against outlining, a vast silence greeted these new products. True, they were gradually incorporated into word processors and presentation packages, but the outlining modules have not been widely used until recently, when two interrelated challenges arose, which these modules help us solve.
Many of us face the challenge of integrating vast amounts of informationmany documents, bits and pieces of questions and answers, bug reports, notes, email chunksinto information CD-ROMs and Web sites. We need to put together the tables of content or menu systems, to clarify the structure so users can navigate confidently, and to identify potential links by category not just by guess and by gosh. And, as we develop the structureand then revise it next week as more information comes pouring inwe must often work with representatives of other departments, subsidiary companies, partner corporations. We find ourselves having to collaborate on the structure. In such circumstances, I recommend you consider using the electronic outlining module in your word processor, possibly for the first time.Outlining software arrives Several computer programs offer us the ability to create outlines electronically. The original dedicated outliners like More® have given way to outlining modules within word processors like Microsoft Word® and Corel Word Perfect®, within the word-processing module of an integrated package (ClarisWorks®), in presentation packages like PowerPoint, and in complex document processors like Adobe FrameMaker+ SGML®.
Electronic outlining does for the outline what word processing has done for the written document. Word processing has gradually transformed our understanding of writing, demonstrating our tendency to switch rapidly back and forth among activities such as brainstorming, notetaking, writing, or organizing; by making it easy to revise, word processing made visible what had been obscured by several decades of teachersthat real writers often revise as they go, that only a small percentage of writers know in advance exactly what they plan to say, that many folks have to go back to the subject matter expert or library to expand on a point in the middle of their writing,and that we may cycle through all these activities in the larger process known as writing.
Similarly, electronic outlining makes visible many activities involved in organizing material, because it makes revising the organization easier than it ever was on paper. Key features that distinguish these electronic outliners from word processors:
Overall, analyzing and revising structure becomes much easier than in a word processing document, so such revision of the arrangement can go on much, much longer than it ever did with a paper outline, carrying you through the whole process from idea to publication. In Word, outlining is considered another view, like the page layout view; in PowerPoint®, the outlining view lets you look at the text of your slides without the art, so you can switch back and forth between the images an audience will see and the ideas you are trying to convey verbally. Electronic outlining, in whatever form, lets us think structurally, and keep on thinking that way as we learn new material. The larger the amount of information, the more we need a robust structure, or else parts will never be found. In this era of gigantic online information piles, we need this tool to plan the structure thoughtfully, and to make sure our headings really reflect their contents in a meaningful way, because so often our headings will serve as items in menus or visual tables of contents, and in hit lists in search mechanisms, guiding the users through hyperspace.Looking back: outlines in a world of paper Outlines were probably inspired by the headings and subheads made popular by early printing. Peter Ramus (1574) suggested that Puritan ministers prepare sermons using a four-part template (summary, major headings with several subheads underneath each, and after each head and subhead, text providing examples and citations). This fill-in-the-blanks outline, with numbered labels to indicate sequence at each level of the hierarchy, gave a form the minister could use to think with, and guaranteed that the result would be an orthodox structure (Batschelet, 1988).
The idea of working with heads and subheads first, then filling in text below, got a boost in the nineteenth century with its elaborate classifications of the natural worldhierarchies within hierarchies. Inspired by the classification systems of botanists, Charles Darwin, for instance, planned each new book by outlining.
For most of the twentieth century, teachers and textbooks have urged students to make an outline before writing. The authorities picture of an outline, though, was heavily if unconsciously shaped by its medium: it is traditionally seen as a document created with pen or pencil on paper, using white space, horizontal positioning, vertical positioning, and labels as visual cues to the semantic relationship between topics. Because handwriting is tedious, few people are willing to rewrite the whole outline to make a few changes, so this paper document often ends up with extra arrows, loops, and speckled crossings outa hard-to-read mess.
This traditional view, then, sees an outline as a product, a single paper document in a series of documents. First you take notes on index cards, then you make a thing called an outline, then you write a draft. Following the etymological origin of the word outline, a few authors of rhetoric and technical writing textbooks have compared the outline with a charcoal sketch, a way of picturing relationships within a composition (Fowler, 1992, p. 35;Hacker, 1994, pp. 102, 107; Martin, 1957, p. 138-9). But several textbook authors over the last fifty years have seen the outline as more precise, like an architects blueprint. [Bell, 1995, p. 80; Brockmann, 1968, p. 49; Hacker, 1994, p. 30; Santmyers, 1949, 46; Thomas, 1949, p. 140; Welborn, 1961, p. 54; Wilcox, 1977, p. 65] While recognizing that a writer may rearrange the pieces to create this plan, the authors tend to emphasize the plan as a pattern that must be followed carefully in creating the draft. A number of authors even insist that writers follow the outline as a kind of map, to avoid getting lost during writing (Alred et al, 1992; Bell, 1995, p. 100; Brusaw, et al, 1993, p. 485; Mills, 1962, p. 44; Santmyers, 1949, p. 35; Shelton, 1995, p. 39 Weisman, 1962, p. 260-261). Well-intentioned as these textbook authors may be, they inadvertently present a static view of the outline as a single, fixed plan.
Such a picture overlooks the cyclical nature of the development process, in which we tend to do a little research, plan a little, write a little more, realize we need to study something in more depth, and so on, cycling through all these activities over and over. The traditional view, articulated most convincingly by Warriner (1959), is that first you study, then you think, then you write down your thoughts in a plan, then you write a draft, based on that outline. How neat!
In reaction to that traditional image, we see writing researchers Hayes and Flower (1980, and Kaufer, Hayes, and Flower (1986) suggest that a writer thinks about a subject, then writes down a plan in the form of an outline. Flower and Hayes (1977, 1981a, 1981b, 1992) attack the outline as a fixed , not a developing plan; a straitjacket; the product of research, but a restraint on any further thinking, leading writers to "paint by numbers--to simply fill in the blanks." (1977, p. 457). In 1984 they contrasted fragmentary and fuzzy plans, which they felt were useful because open to continuing development, with those "more formal, logical, and limited plans associated with outlines and notes" (1984, p. 124), which they condemned.
Recent research, though, suggests that the various processes that go into writing occur again and again, overlapping, one provoking another, cyclically [Hult and Harris, 1987; Kostelnick, 1989a; Moberg, 1986; Schwartz, 1985]. Walvoord et al (1995) note, however:
We do know that most writers contemplating a short paper piece ignore outlining altogether. [Bereiter and Scardamalia, 1987; Emig, 1971; Hillocks, 1986; Mischel, 1974; Perl, 1979; Pianko, 1979; Stallard, 1974]. But writers facing a longer and more complicated printed document often do outline, according to the researchers (Emig, 1971; Kellogg, 1988; Kulthau, 1988; McCarthy, 1985; Nelson, 1992; Sommers and McQuade, 1984; Stein, 1990; Taylor and Beach, 1984). Professional writers, who commonly work on several book-length projects at once, regularly produce a detailed table of contents showing several levels of headings, as part of the document design, while working out a schedule with their teameffectively, an outline that serves as a contract of work to be done. And now that we are becoming responsible for Web sites giving the public access to thousands of documents, we need a tool that will allow us to organize them meaningfully and keep revising that organization as new materials pour in upon us.
Making it easier to improve structure as you go
Electronic outlining gives us many ways to consider and change the structure of our information. Many of us intuitively carry out these activities of structural analysis, construction, and rebuilding whenever we are making up a table of contents as part of our document design. But we often work within that structure as a given, and write to justify it, even when we begin to sense that there are some problems. (Often these problems blow up in our faces at the beta review meeting, when we have very little time to solve them).
Now, increasingly, we have to revise structure on an ongoing basis for Web sites, and even if we are just putting together a CD-ROM, we keep getting new ideas, new input, new marketing tilts well along in the process, so we need to be able to keep changing the structure much later in the project than ever before.
Because of these changes, we need to be more conscious of the wide range of interrelated activities involved in structuring information, the intellectual strategies that electronic outliners make easier to carry out.
As we use these strategies, the electronic outliner serves as a tool for thinking. The thinking can be described as ordinary, that is, following common patterns of thought, ones we hope our users will recognize. Like a Lego kit, the pieces of the outline can be reassembled in many different ways, allowing us to consider the rhetorical impact of each new structure, and then, without losing track of that, to ponder the effectiveness of an alternate structure. By externalizing our own thoughts, we can interrogate them; in effect, we carry on a conversation with our thought of just a minute ago.
This process, when carried out week after week during a developing project, means that we encounter many of the problems with our earlier organization. We learn as we go, and revise the structure to reflect our deeper knowledge. The outline, like the document, remains open.
This openness contrasts dramatically with the traditional model, which conceives of a writer locating a number of "facts" through research, then applying something called "logic" to those facts, and then recording the "thoughts" that emerged in an outline, to serve as a blueprint for the document that would be built mainly by "expanding" on those thoughts in the draft. [Alvarez, 1980, p. 157; Brusaw et al, 1993, p. 485; Damerst, 1982, p. 59; Dietrich, 1958, 109-111; Elsbree, 1967, p. 39; Fowler et al, 1992, p. 39; Hacker, 1994, p. 46; Hacker & Renshaw, 1979, p. 107; Harwell, 1960, pp.122-3; Hays, 1965, p. 104; Johnson, 1992, p. 141; Jordan, 1965, pp. 108-111; Leggett, 1960, pp. 196-7; Lester, 1990, p. 114; Marckwardt, 1960, p. 408; Markel, 1984, p. 70; Mills, 1962, p.45; Rubens, 1992, p. 15; Shelton, 1995, p. 42; Sherman, 1955, p. 12, 1966, p. 34; Smart, 1943, pp. 19-26; Thomas, 1949, pp. 130-142; Weiss, 1982, p. 52 ; Wellborn, 1961, p. 55; Wicker, 1960, p. 54; Wilcox, 1977, p. 83-86] Now, in electronic outlining, these activities overlap, so outlining takes place alongside research, brainstorming, and writing. A few examples:
Thus, electronic outlining allows structuring to take its full place as part of the whole process of creating meaningful information, a process we used to call writing.
Notice that I do not regard formatting as one of the intellectual strategies involved in structuring. Using a different style (font, size, color, indent, so on) for each level helps clarify the structure, and reveal it, making it easier to manipulate (Apple Computer, 1987; Hutchins et al., 1986; Shneiderman, 1983; Young, 1991). But we do not spend as much effort on labeling (I, II, IIa, IIb, and so on) as we did in the paper world, and we do not face a tangle of crossouts and overlays when we make changes, as we did on paper. After every change we have a clean outline, ready for further study and work.
Developing more effective tables of contents and menus
Imagine the challenge of putting 200 documents from eight different divisions into a single information system. You are looking at a larger and more complex table of contents than you ever saw in a book, or suite of books. Now your boss tells you that you have to present all those documents on the Web site, plus, incidentally, 500 application notes, 100 documents answering frequently asked questions, all the press releases from the last year, and the annual report. What does your table of contents, or menu system, look like now?
As the volume of information increases, not just arithmetically, but exponentially, we find we must pay more attention to creating meaningful menu systems. In their book on web design, Horton, Taylor, Ignacio, and Hoft (1996) suggest dozens of cluster structures, depending on your purpose, and you will no doubt create more; but what you must create for the user is a series of menus, whether they look like a books tables of contents, pulldown menus, tables with rows and columns, maps, or hot images.
The electronic outliner lets you analyze and improve your menus, because it gives you quick answers to questions such as:
The electronic outliner also helps you modify menus to respond to the demands of your user interface czar. For instance, menus in a graphic user interface are supposed to help users recognize the action they want to take, rather than remember a weird command, but the user should not have to recall what was on a previous menu in order to understand what is on the menu now visible, a common problem, as Mandel (1996) points out, (p. 154). By isolating the menu in your outliner, you can rewrite the items so the menu stands on its own, without depending on our knowing what topic we chose earlier.
To keep from blowing peoples short-term memory, many UI folks request that you separate a longish menu into smaller groups (less than 7 items each, as in Mandel, 1996, p. 154). Using the outliner, you can experiment with various possible groupings, tinkering until they fit (and, hopefully, make sense).
Your interface may accommodate graphic, verbal, push-button, radio-button, check-box, pull-down, pop-up, and cascading menus. You need to decide which kind of menu to use at each level. And once you have decided the type of menu youll use at, say, the fourth level, you may need to go back and rewrite those particular headings so they work in that environment. For instance, you may need to compact your text dramatically, to make it fit.
Improving navigation by clarifying structure
As users move through your online information, they build a mental map of the structure. Like people walking through a city, users remember the decision points better than the material in between; that is, they remember whenever they chose to make a turn (Lynch, 1960, p. 72) or, in hypertext terms, a jump. When users can recall each choice, in order, they feel secure. But most people have short-term memory capable of recalling only 7 plus or minus 2 items (Miller, 1956). So if you force people to make more than 5 or 6 decisions on the trail of a fact, many folks begin to lose track of the trail itself. In extreme cases, the users begin to feel lost in hyperspace, and experience hypernausea.
Your structure acts as a model for users, reassuring them that they can predict where they will go next, and that they can remember where they have been. Newcomers to a content area often find that a well-defined, conventional structure helps them decide what is important and what is not (Johnson-Eilola, 1994, p. 207; van Dijk and Kintsch, p. 55-59). If you write your menus with as much carelessness as most book authors do their tables of contents, users may get lost. Charney summarizes a lot of research when she says that readers "understand and learn most easily from texts with well-defined structures that clearly signal shifts between parts (1994, p. 207). In fact, having a structural overview at hand during a search through the material increases recall, recognition of relations, and inferences (p. 252). But when users encounter gaps they cannot understand, they make up bridging guesses, as Harpold (1990, p. 177) and Johnson-Eilola (1994, p. 212) point out happens in poorly organized hypertext environments. Result: confusion. Charney concludes: "If the goal is to ensure that readers consider a specific set of associations, then a highly organized text format is more likely to achieve that aim than an amorphous network." (p.243). Her recommendation echoes good sense:
If your interface allows the user to consult your outline at all times, as in Folio Views®, Dynatext®, or FrameMaker + SGML, then you can see how often users flicker back and forth between text and outline, trying to understand why the material appears where it does, in the hierarchy. The same mental back-and-forth movement takes place even when the interface does not allow the user to view an open outline on the side, as a guide to the material; users constantly ask themselves, "Am I in the right place? Did I reach the target I expected? Is this really what I thought it would be, or was I fooled by that last menu item?"
In a book, users have developed many strategies for overcoming poor organization: skimming the headings, browsing the text, flipping pages looking for the next chapter. None of these strategies works well online because the low resolution defeats skimming and browsing, and you cant flip pages. As a result, users must rely much more heavily on your heads and subheads to get a sense of location in a sequence and position in a hierarchy. Your outline, translated into a menu system, bears a heavier responsibility for the users sense of place, and ability to move through your information world.
Fortunately, an electronic outliner allows you to examine and revise each heading in two ways: as one item in a menu, and as a heading at the top of a virtual page of material. As an item in a menu, it must stand out from the others, while advertising its content well enough so no one picks it by mistake, and anyone looking for that content spots it and chooses it right away. Then, when the user arrives at the page (frame, block, window, screen, whatever), the heading at the top of the page must match the menu item exactly, to confirm that the user has arrived at the right place. And the first paragraph of text must explain the heading, as an extra confirmation. Because the outliner lets you look at the item in its menu (without any following text), then with the attached text, you can consider it both ways, like a user. In this environment, revision means rewriting to articulate the reasoning behind the structure as well as reorganizing the structure itself.
Identifying categories of information that should be link targets
When writers first get an opportunity to create hypertext links, they tend to make them up here, there, and everywhere. These ad-hoc links are acceptable in a personal home page, but become disturbing when you need to look something up. For instance, you see that the names of a few activities are hot, but not others: what is the difference? Is it significant? Have you perhaps misunderstood the relationship between them?
Generally, before creating a hypertext package such as a Web site or help system, you should decide what categories of information you expect to make into links. Clearly, topics in menus will be hot, and if you refer to a topic that exists somewhere else, that reference should be hot. But what else becomes a link? Any term in the glossary could be made into a link, anywhere it appears in the text: that would be a category. Any technique mentioned could be made into a link to the video that shows how to perform that technique. Your outline need not record all links, but it must account for all targets, so you can check for completeness. For instance, you would probably have a top level section called Glossary, and another called Technique Videos.
The electronic outliner helps you collect these link categories, order them, and verify the completeness of your lists. You can make sure that no foreign elements creep in. You can confirm that your headings are parallel in form, to reassure the user that they all present the same kind of material; and you can measure the lists for completeness, accuracy, and sequence.
Facilitating collaboration at every stage
Just as word processing helped writers exchange drafts, criticize and discuss their works together, and even collaborate on documents (Costanzo, 1994; Duin & Hansen, 1994; Ede and Lunsford, 1990; Eldred, 1989; Hawisher, 1994; Humphrey, 1987; Rodrigues & Rodrigues, 1986), electronic outlining helps two or three writers work together sharing the same keyboard, looking at the same screen, as they develop a structure they all can agree on and carry out. Thats direct collaboration. Theorists have recognized that creating hypertexts together fosters the exchange of views and consolidation of ideas in a group (Adelson and Jordan, 1992; Irish and Trigg, 1989; Johnson-Eilola, 1994), but these experiments tend to rely on software explicitly created to allow people to make hypertext links. Electronic outlining, because it focuses on structure more than running text or links, actually offers professional writers a better tool than either word processors or hypertext editors, at least for collaborating where it counts, that is, at the level of organization, not links and phrases. In my experience collaborating with one to five other writers on five manuals, and half a dozen help systems for computer companies such as Apple, Claris, Epson, and GO, I have seen that when a team reaches full agreement on the organization, team members can consistently carry out stylistic decisions and insert links, without having to consult each other. But when the team has not beaten the rough edges off a structure, any attempts at individual writing go rapidly astray, resulting in patches of redundancy, inconsistency, ambiguity, failed transitions, and confusion.
Why is an electronic outliner such a helpful tool for collaborating on the organization of your online material?
Increasingly you are being asked to publish vast amounts of information. You do not have time to rewrite much of it. Your attention must turn to organizing it so a user can find key sections, either through the menu system or a search mechanism. The outliner lets you and other members of your team create and interrogate a structure, down to whatever level you want, viewing it as a user might, ironing out the ambiguities, overlaps, duplications, and detours. You cannot afford to allow each group or individual to create its own outline, because then the various outlines will not fit together in a consistent, understandable way. You must meet, and when you meet, you should use an electronic outline as a way of keeping notes on your evolving agreement.
Whether you are working alone or with a team, the electronic outliner offers a way to create and revise the structure of large, complicated information systems, spinning off menus and links, improving navigation through the environment. Increasingly, our work is becoming an ongoing process of facilitating the flow of information, not issuing books; an important part of our contribution becomes the constant revision of the structures greeting our users. So, forgive your dear old English teachers. They meant well. And now, with electronic outlining, you can do everything they hoped you would do, back thenand more.References
Copyright 1997-2001 Jonathan and Lisa Price, The Communication Circle
Return to our site at http://www.theprices.com/circle
Email us at JonPrice@AOL.com