Norway


A few years ago, a former boss of mine emailed me out of the blue and asked for a resource that would help him and his colleagues organize information more effectively. Like a dutiful friend, I sent him links to a few articles and the names of some professional writing books. And I qualified my answer with that dreaded disclaimer: “Advice varies widely depending on the situation.” Implication: “You’ll just have to figure out what works best for you. So, good luck!”

Article Continues Below

In retrospect, I could have given him a better answer. Much like the gestalt principles of design that underpin so much of what designers do, there are foundational principles and patterns of organization that are relevant to any professional who must convey technical information in writing, and you can adapt these concepts to bring order out of chaos whether or not you’re a full-time writer.

Recognize the primary goals: comprehension and performance

Not long after I wrote my response, I revisited a book I’d read in college: Technical Editing, by Carolyn D. Rude. In my role as a technical writer, I reference the book every now and then for practical advice on revising software documentation. This time, as I reviewed the chapter on organization, I realized that Rude explained the high-level goals and principles better than any other author I’d read up to that point.

In short, she says that whether you are outlining a procedure, describing a product, or announcing a cool new feature, a huge amount of writing in the workplace is aimed at comprehension (here’s what X is and why you should care) and performance (here’s how to do X). She then suggests that editors choose from two broad kinds of order to support these goals: content-based order and task-based order. The first refers to structures that readers from sections to more detailed sections to facilitate top-down learning; the second refers to structures of actions that readers need to carry out. Content-based orders typically start with nouns, whereas task-based orders typically begin with verbs.

Content-Based Order Example

Product Overview

  • Introduction
  • Features
    • Feature 1
    • Feature
    • Feature n
  • Contact
  • Support

Task-Based Order Example

User Guide (WordPress)

  • Update your title and tagline
  • Pick a theme you love
  • Add a header or background
  • Add a icon
  • Add a widget

Of course, not all writing situations fall neatly into these buckets. If you were to visit Atlassian’s online help content, you would see a hybrid of content-based topics at the first level and task-based topics within them. The point is that as you begin to think about your organization, you should ask yourself:

  • Which of the major goals of organization (comprehension or performance) am I trying to achieve?
  • And which broad kind of order will help me best achieve those goals?

This is still pretty abstract, so let’s consider the other principles from Carolyn Rude, but with a focus on how a writer rather than an editor should approach the task of organization.1

Steal like an organizer: follow pre-established document structures

In his book Steal Like an Artist, Austin Kleon argues that artists don’t actually create anything new but rather collect inspiring ideas from specific role models, and produce work that is profoundly shaped by them.

“If we’re free from the burden of trying to be completely original,” he writes, “we can stop trying to make something out of nothing, and we can embrace influence instead of running away from it.”

The same principle applies to the art of organization. To “steal like an organizer” means to look at what other people have written and to identify and follow pre-established structures that may apply to your situation. Doing so not only saves time and effort but also forces you to remember that your audience may already expect a particular pattern—and experience cognitive dissonance if they don’t get it.

You are probably familiar with more pre-established structures than you think. reports follow the inverted pyramid. Research reports often adhere to some form of the IMRAD structure (Introduction, Methodology, Results, and Discussion). Instruction manuals typically have an introductory section followed by tasks grouped according to the typical sequence a user would need to follow. Even troubleshooting articles tend to have a standard structure of Problem, Cause, and Solution.

All this may sound like common sense, and yet many writers entirely skip this process of adapting pre-made structures. I can understand the impulse. When you face a blank screen, it feels simpler to capture the raw notes and organize it all later. That approach can certainly help you get into the flow, but it may also result in an ad hoc structure that fails to serve readers who are less familiar with your material.

Instead, when you begin the writing process, start by researching available templates or pre-made structures that could support your situation. Standard word processors and content management systems already contain some good templates, and it’s easy to search for others online. Your fellow writers and designers are also good resources. If you’re contributing to a series of documents at your organization, you should get familiar with the structure of that series and learn how to work within it. Or you can do some benchmarking and steal some ideas from how other companies structure similar content.

My team once had to do our own stealing for a major project that affected about half our company. We needed to come up with a repeatable structure for standard operating procedures (SOPs) that any employee could use to document a set of tasks. Knowing SOPs to be a well-established genre, we found several recommended structures online and in books, and came up with a list of common elements. We then decided which ones to steal and arranged them into a sequence that best suited our audience. We made out like bandits.

Structural SOP Elements We Found Our Assessment
Overview Steal
Roles Involved Steal
Dependencies Steal
Estimated Level of Effort Nah, too hard to calculate and maintain.
Process Diagram Meh, kind of redundant, not to mention a lot of work. No thanks.
Tasks Steal
Task n Steal
Task n Introduction Steal
Task n Responsibility Steal
Task n Steps Steal
See Also Steal

But what if there is no pre-established pattern? Or what if a pattern exists, but it’s either too simple or too complex for what you’re trying to accomplish? Or what if it’s not as user-friendly as you would like?

There may indeed be cases where you need to develop a mostly customized structure, which can be daunting. But fear not! That’s where the other principles of organization come in.

Anticipate your readers’ questions (and maybe even talk to them)

Recently I had an extremely frustrating user experience. While consulting some documentation to learn about a new process, I encountered a series of pages that gave no introduction and dove straight into undefined jargon and acronyms that I had never heard of. When I visited related pages to get more context, I found the same problem. There was no background information for a newbie like me. The writers failed in this case to anticipate my questions and instead assumed a great deal of prior knowledge.

Don’t make this mistake when you design your structure. Like a journalist, you need to answer the who, what, where, when, how, and why of your content, and then incorporate the answers in your structure. Anticipate common questions, such as “What is this? Where do I start? What must I know? What must I do?” This sort of critical reflection is all the more important when organizing web content, because users will almost certainly enter and exit your pages in nonlinear, unpredictable ways.

If possible, you should also meet with your readers, and gather information about what would best serve them. One simple technique you could try is to create a knowledge map, an annotated matrix of sorts that my team once built after asking various teams about their information priorities. On the left axis, we listed categories of information that we thought each team needed. Along the top axis, we listed a column for each team. We then gave team representatives a chance to rank each category and add custom categories we hadn’t included. (You can learn more about the process we followed in this video presentation.)

A screenshot of a knowledge map my team created after asking other teams which categories of information were most important to them.  - fig1 - Patterns of Organization for Writing on the Job · An A List Apart Article
A knowledge map my team created after asking other teams which categories of information were most important to them.

The weakness of this approach is that it doesn’t reveal information that your audience doesn’t know how to articulate. To fill in this gap, I recommend running a few informal usability tests. But if you don’t have the time for that, building a knowledge map is better than not meeting with your readers at all, because it will help you discover structural ideas you hadn’t considered. Our knowledge map revealed multiple categories that were required across almost all teams—which, in turn, suggested a particular hierarchy and sequence to weave into our design.

Go from general to specific, familiar to new

People tend to learn and digest information best by going from general to specific, and familiar to new. By remembering this principle, which is articulated in the schema theory of learning, you can better conceptualize the structure you’re building. What are the foundational concepts of your content? They should appear in your introductory sections. What are the umbrella categories under which more detailed categories fall? The answer should determine which headings belong at the top and subordinate levels of your hierarchy. What you want to avoid is presenting new ideas that don’t flow logically from the foundational concepts and expectations that your readers bring to the table.

Consider the wikiHow article “How to Create a Dungeons and Dragons Character.” It begins by defining what Dungeons and Dragons is and explaining why you need to create a character before you can start playing the game.

A screenshot of Part 1 of the wikiHow article “How to Create a Dungeons and Dragons Character,” which helps readers learn by starting with general concepts before moving on to specifics.  - fig2 - Patterns of Organization for Writing on the Job · An A List Apart Article
Writers at wikiHow help readers learn by starting with general concepts before moving on to specifics.

The next section, “Part 1: Establishing the Basics,” guides the reader into subsequent foundational steps, such as deciding which version of the game to follow and printing out a character sheet. Later sections (“Selecting a gender and race,” “Choosing a class,” and “Calculating ability scores”) expand on these concepts to introduce more specific, unfamiliar ideas in an incremental fashion, leading readers up a gentle ramp into new territory.

Use conventional patterns to match structure to meaning

Within the general-to-specific/familiar-to-new framework, you can apply additional patterns of organization that virtually all humans understand. Whereas the pre-established document structures above are usually constructed for particular use cases or genres, other conventional patterns match more general mental models (or “schemas,” as the schema theory so elegantly puts it) that we use to make sense of the world. These patterns include chronological, spatial, comparison-contrast, cause-effect, and order of importance.

Chronological

The chronological pattern reveals time or sequence. It’s appropriate for things like instructions, process flows, progress reports, and checklists. In the case of instructions, the order of tasks on a page often implies (or explicitly states) the “proper” or most common sequence for a user to follow. The wikiHow article above, for example, offers a recommended sequence of tasks for beginner players. In the case of progress reports, the sections may be ordered according to the periods of time in which work was done, as in this sample outline from the book Reporting Technical Information, by Kenneth W. Houp et al.:

Beginning

  • Introduction
  • Summary of work completed

Middle

  • Work completed
  • Work remaining

    • Period 3 (or remaining periods)
      • Description of work to be done
      • Expected cost

End

  • Evaluation of work in this period
  • Conclusions and recommendations

The principles of organization listed in this article are in fact another example of the chronological pattern. As Carolyn Rude points out in her book, the principles are arranged as a sort of methodology to follow. Try starting at the top of the list and work your way down. You may find it to be a useful way to produce order out of the chaos before you.

Spatial

The spatial pattern refers to top-to-bottom, left-to-right structures of organization. This is a good pattern if you need to describe the components of an interface or a physical object.

Take a look at the neighbor comparison graph below, which is derived from a sample energy efficiency solution offered by Oracle Utilities. who see this graph would most likely view it from top to bottom and left to right.

A neighbor comparison graph that shows a customer how they compare with their neighbors in terms of energy efficiency.  - fig3 - Patterns of Organization for Writing on the Job · An A List Apart Article
A neighbor comparison graph that shows a customer how they compare with their neighbors in terms of energy efficiency.

A detailed description of this feature would then describe each component in that same order. Here’s a sample outline:

  • Feature name
    • Title
    • Bar chart
      • Efficient neighbors
      • You
      • Average neighbors
    • Date range
    • Performance insight

      • Great
      • Good
      • Using more than average
    • Energy use insight
    • Comparison details (“You’re compared with 10 homes within 6 miles …”)

Comparison-contrast

The comparison-contrast pattern helps users weigh options. It’s useful when reporting the pros and cons of different decisions or comparing the attributes of two or more products or features. You see it often when you shop online and need to compare features and prices. It’s also a common pattern for feasibility studies or investigations that list options along with upsides and downsides.

Cause-effect

The cause-effect pattern shows relationships between actions and reactions. Writers often use it for things like troubleshooting articles, medical diagnoses, retrospectives, and root cause analyses. You can move from effect to cause, or cause to effect, but you should stick to one direction and use it consistently. For example, the cold and flu pages at Drugs.com follow a standard cause-effect pattern that incorporates logical follow-up sections such as “Prevention” and “Treatment”:

  • What Is It? (This section defines the illness and describes possible “causes.”)
  • Symptoms (This section goes into the “effects” of the illness.)
  • Diagnosis
  • Expected Duration
  • Prevention
  • Treatment
  • When to Call a Professional
  • Prognosis

For another example, see the “Use parallel structure for parallel sections” section below, which shows what a software troubleshooting article might look like.

Order of importance

The order of importance pattern organizes sections and subsections of content according to priority or significance. It is common in announcements, marketing brochures, release notes, advice articles, and FAQs.

The order of importance pattern is perhaps the trickiest one to get right. As Carolyn Rude says, it’s not always clear what the most important information is. What should come in the beginning, middle, and end? Who decides? The answers will vary according to the author, audience, and purpose.

When writing release notes, for example, my team often debates which software update should come first, because we know that the decision will underscore the significance of that update relative to the others. FAQs by definition are focused on which questions are most common and thus most important, but the exact order will depend on what you perceive as being the most frequent or the most important for readers to know. (If you are considering writing FAQs, I recommend this great advice from technical writer Lisa Wright.)

Other common patterns

Alphabetical order is a common pattern that Rude doesn’t mention in detail but that you may find helpful for your situation. To use this pattern, you would simply list sections or headings based on the first letter of the first word of the heading. For example, alphabetical order is used frequently to list API methods in API documentation sites such as those for Flickr, Twitter, and Java. It is also common in glossaries, indexes, and encyclopedic reference materials where each entry is more or less given equal footing. The downside of this pattern is that the most important information for your audience may not appear in a prominent, findable location. Still, it is useful if you have a large and diverse set of content that defies simple hierarchies and is referenced in a non-linear, piecemeal fashion.

Group related material

Take a look at the lists below. Which do you find easier to scan and digest?

  1. Settle on a version of D&D.
  2. Print a character sheet, if desired.
  3. Select a gender and race.
  4. Choose a class.
  5. Name your character.
  6. Identify the main attributes of your character.
  7. Roll for ability scores.
  8. Assign the six recorded numbers to the six main attributes.
  9. Use the “Point Buy” system, alternatively.
  10. Generate random ability scores online.
  11. Record the modifier for each ability.
  12. Select skills for your character.
  13. List your character’s feats.
  14. Roll for your starting gold.
  15. Equip your character with items.
  16. Fill in armor class and combat bonuses.
  17. Paint a picture of your character.
  18. Determine the alignment of your character.
  19. Play your character in a campaign.

Part 1: Establishing the Basics

  1. Settle on a version of D&D.
  2. Print a character sheet, if desired.
  3. Select a gender and race.
  4. Choose a class.
  5. Name your character.

Part 2: Calculating Ability Scores

  1. Identify the main attributes of your character.
  2. Roll for ability scores.
  3. Assign the six recorded numbers to the six main attributes.
  4. Use the “Point Buy” system, alternatively.
  5. Generate random ability scores online.
  6. Record the modifier for each ability.

Part 3: Equipping Skills, Feats, Weapons, and Armor

  1. Select skills for your character.
  2. List your character’s feats.
  3. Roll for your starting gold.
  4. Equip your character with items.
  5. Fill in armor class and combat bonuses.

Part 4: Finishing Your Character

  1. Paint a picture of your character.
  2. Determine the alignment of your character.
  3. Play your character in a campaign.

(Source: wikiHow: How to Create a Dungeons and Dragons Character.)

If you chose the second list, that is probably because the writers relied on a widely used organizational technique: grouping.

Grouping is the process of identifying meaningful categories of information and putting information within those categories to aid reader comprehension. Grouping is especially helpful when you have a long, seemingly random list of information that could benefit from an extra layer of logical order. An added benefit of grouping is that it may reveal where you have gaps in your content or where you have mingled types of content that don’t really belong together.

To group information effectively, first analyze your content and identify the discrete chunks of information you need to convey. Then tease out which chunks fall within similar conceptual buckets, and determine what intuitive headings or labels you can assign to those buckets. Writers do this when creating major and minor sections within a book or printed document. For online content, grouping is typically done at the level of articles or topics within a web-based system, such as a wiki or knowledge base. The Gmail Help Center, for example, groups topics within categories like “Popular articles,” “Read & organize emails,” and “Send emails.”

It’s possible to go overboard here. Too many headings in a short document or too many topics in a small help system can add unnecessary complexity. I once faced the latter scenario when I reviewed a help system written by one of my colleagues. At least five of the topics were so short that it made more sense to merge them together on a single page rather than forcing the end user to click through to separate pages. I’ve also encountered plenty of documents that contain major section headings with only one or two sentences under them. Sometimes this is fine; you may need to keep those sections for the sake of consistency. But it’s worth assessing whether such sections can simply be merged together (or conversely, whether they should be expanded to include more details).

Because of scenarios like these, Carolyn Rude recommends keeping the number of groupings to around seven, give or take a few—though, as always, striking the right balance ultimately depends on your audience and purpose, as well as the amount of information you have to manage.

Use parallel structure for parallel sections

One of the reasons Julius Caesar’s phrase “I came, I saw, I conquered” still sticks in our memory after thousands of years is the simple fact of parallelism. Each part of the saying follows a distinct, repetitive grammatical form that is easy to recall.

Parallelism works in a similar manner with organization. By using a consistent and repetitive structure across types of information that fit in the same category, you make it easier for your readers to navigate and digest your content.

Imagine you’re writing a troubleshooting guide in which all the topics follow the same basic breakdown: Problem Title, Problem, Cause, Solution, and See Also. In this case, you should make sure that each topic includes those same headings, in the exact same hierarchy and sequence, and using the exact same style and formatting. This kind of parallelism delivers a symmetry that reduces the reader’s cognitive load and clarifies the relationships of each part of your content. Deviations from the pattern not only cause confusion but can undermine the credibility of the content.

Do This

ABC Troubleshooting Guide

  • Introduction
  • Problem 1 Title
    • Problem
    • Cause
    • Solution
    • See Also
  • Problem 2 Title

    • Problem
    • Cause
    • Solution
    • See Also
  • Problem 3 Title

Don’t Do This

ABC Troubleshooting Guide

  • Introduction
  • Problem 1 Title
    • Problem
    • Root causes
    • How to Fix it
    • Advanced Tips and tricks
    • Related
  • Problem 2 title

    • Issue
    • Steps to Fix
    • Why did this happen, and how can I avoid it next time?
    • See also
  • Problem 3 title

This last principle is probably the easiest to grasp but may be the most difficult to enforce, especially if you are managing contributions from multiple authors. Templates and style guides are useful here because they invite authors to provide standard inputs, but you will still need to watch the content like a hawk to squash the inconsistencies that inevitably emerge.

Conclusion

In one sense, my response to my former boss was accurate. Given the endless variety of writing situations, there is no such thing as a single organization solution. But saying that “advice varies widely depending on the situation” doesn’t tell the whole story. There are flexible patterns and principles that can guide you in finding, customizing, and creating structures for your goals.

The key thing to remember is that structure affects meaning. The sequence of information, the categories you use, the emphasis you imply through your hierarchy—all of these decisions impact how well your audience understands what you write. Your ideal structure should therefore reinforce what you mean to say.





Source link

LEAVE A REPLY

Please enter your comment!
Please enter your name here