Search results

Organizing for Learnability [Organizing Content #25]

Series: Findability / organizing content

by Tom Johnson on Sep 1, 2010
categories: findability technical-writingwordpress

Last week I attended WordCamp Utah and spoke with one of the "happiness engineers" who works at Automattic. (Automattic is the the company that provides and also leads development of the open-source WordPress software.) The happiness engineer, Sherri, told me about a new alternative to the Codex and Help for ramping up on WordPress:

At first glance, looks plain and somewhat un-instructive, put together by someone who is straining for offbeat graphics and simplicity. The new online quick start guide for WordPress

However, if you read the content, the site accomplishes two things that a lot of help material fails to do:

  1. The help proceeds in a sequential, screen-by-screen way, rather than overwhelming the user with too much content at once. This helps lead the reader along in a staircase-like fashion rather than requiring the user to scale a steep wall all at once.
  2. The help combines strategy with technical procedures. For example, the entire second step, Get Focused, discusses strategy rather than technical how-to steps. We often forget to incorporate strategy in our help material, getting lost in the 1-2-3 of the steps. But really, figuring out your blog's focus is probably the single most difficult aspect of starting a successful blog.

My happiness engineer also said that someone at WordPress is writing handbooks about various WordPress topics. I assume the content on would fit well into a handbook format.

Both of these principles address how to organize content, which is part of my ongoing series.

Screen-by-Screen Tutorial Organization

A University of Wisconsin guideline on web development classifies sites that provide tutorials as "training sites" and recommends a screen-by-screen chunking of the information:

Training sites are meant to guide a user through some sort of process. The user experience is carefully controlled through a series of linear links. Due to the linear organization, which requires a user to digest information in a steady stream, information is brief on each page. Links to other pages and sites are limited and only used to supplement the material being presented. Training sites follow a: step1 - step 2 - step 3, structure.

Training sites have this screen-by-screen structure

Training sites have this screen-by-screen structure

The author gives two examples: PowerPoint in the Classroom and HTML Code Tutorial.

Not all tutorial sites chunk information up into small bites on each screen. A few years ago I tried to write a quick reference guide to WordPress and ended up sticking it all in one long view on the same wiki page. Arranging all the information on one page is not an appealing format. Its length is uninviting, and there are no visuals to break up the endless text readers have to scroll through.

I'm not the only one guilty of creating tutorials that require users to scroll and scroll and scroll. Here's one on jQuery from Authentic Society. And here's a tutorial on WordPress from Webmonkey.

In comparing the screen-by-screen organization versus the all-in-one-screen organization, which do you prefer? Here are my observations:

  • The screen-by-screen organization is less intimidating. I'm able to consume it one bite at a time.
  • The screen-by-screen organization includes its own navigation structure, usually a table of contents in a sidebar along with navigation arrows at the end of each screen. This navigation structure is usually separate from the overall site's navigation.
  • The screen-by-screen organization prompts me to move one step at a time, rather than scrolling quickly past paragraphs and paragraphs of content.

Findability Versus Learnability

I'm not sure why, but I rarely arrange my help content in a screen-by-screen organization. One obstacle is that I often chunk content into small topics to enable reusability within my project deliverables. The topic-based authoring paradigm seems to run counter to screen-by-screen arrangements, which concatenate many separate topics into one long tutorial. Another reason I haven't used more screen-by-screen arrangements is because, as a technical writer, I'm more focused on accuracy and completeness of information rather than how learnable or transferrable the information is to users.

As such, I'm more inclined to aggregate all the information onto one page, using the all-in-one-screen organization, or to divide each section into its own individual topic and present all the topics in a table of contents. But an instructional designer would be more inclined to arrange the content into a screen-by-screen presentation, because instructional designers know that if they want the user to actually absorb the material, they have to feed it to the user little by little, just as you pour water into an iron's water reservoir. Pour the water slowly and in a small stream, and it goes into the iron's reservoir without a problem. Dump the whole glass of water into the iron's reservoir at once, and it runs everywhere except into the reservoir.

Despite these differences of approach between tech comm and instructional design, our overall goals are the same: to help users understand a technical process or concept. Keith Hopper noted in his STC Summit talk on The Convergence of Tech Comm and Instructional Design that the practices of technical communication overlap with instructional design in so many ways, it doesn't make sense to keep them separate.

In organizing content, I've chiefly been asking about the best way to organize the help content to increase its findability. I assumed that if users can find the answer, they could solve the problem and go about their merry way. But perhaps the more important question to explore is how to organize help content to increase its learnability. That question leads to an entirely different method of organization.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.