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.
However, if you read the content, the site accomplishes two things that a lot of help material fails to do:
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.
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.
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.
In comparing the screen-by-screen organization versus the all-in-one-screen organization, which do you prefer? Here are my observations:
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.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.