Document 360: #1 Knowledge Base Software
Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,400+ subscribers

Search results

Document 360: #1 Knowledge Base Software

Organizing for Learnability [Organizing Content #25]

by Tom Johnson on Sep 1, 2010 •
categories: findabilitytechnical-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 WordPress.com and also leads development of the open-source WordPress software.) The happiness engineer, Sherri, told me about a new alternative to the Codex and WordPress.com Help for ramping up on WordPress: learn.wordpress.com.

At first glance, learn.wordpress.com looks plain and somewhat un-instructive, put together by someone who is straining for offbeat graphics and simplicity.

Learn.wordpress.com
Learn.wordpress.com: 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 learn.wordpress.com 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.

Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,400+ subscribers

follow us in feedly

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.

Comments
https://idratherbewriting.com/2010/09/01/organizing-for-learnability-organizing-content-25/
idratherbewriting.com
crawl=CC-MAIN-2020-29
74125
application/http; msgtype=response
sha1:U2FELGDCXM4ZH7VCEKBBZ6GGZTLQFQK6
<urn:uuid:01f1056d-40bc-49df-a6ee-c400ca331c08>
2020-07-16T18:09:44Z
104.27.149.230
text/html
sha1:J3WJRDM4XZJI3NLBJZSGNH2O6DZ5H36H
<urn:uuid:aaa59e8f-ce1f-4585-b98c-533b3cb20681>
https://idratherbewriting.com/2010/09/01/organizing-for-learnability-organizing-content-25/
response
<urn:uuid:40dd85a0-c645-486b-bc4a-17a81e6365d3>
isPartOf: CC-MAIN-2020-29
publisher: Common Crawl
description: Wide crawl of the web for July 2020
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-67-67-211.ec2.internal
software: Apache Nutch 1.17 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 1.2-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: http://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/