How to Organize Page-Level Content

One of the topics I haven’t covered is how to organize content within the same page. If your topics become long and look more like Wikipedia pages, you will have a lot of content to organize — potentially twenty different sections on the page, including both tasks and concepts. What’s the best way to organize all your page-level content?

Although many users, being action-oriented and looking to do something, may skip straight to a task, this doesn’t mean you should mix all your conceptual information with the task information just so users will read it. If you start mixing concepts with tasks, when you create a new task that relies on the same concept, you’ll end up repeating the concept.

For example, look at this problematic task.

To install a plugin:

  1. To install a new plugin, go to the Plugins page. Plugins are like modules in Drupal or extensions in other programs — they add more functionality to the software. There are thousands of plugins to choose from, but keep in mind that many are created by third-party developers and are in varying states of development — some haven’t been updated for years and may no longer work with the latest version of WordPress.
  2. Click Add New.
  3. Browse to the zip file to upload it. After you upload it, activate it.
  4. Once uploaded, look for the settings page. Most plugins have a page under the Settings menu that provides information about configuring the plugin, including instructions on how to use it. If it’s not under Settings, try checking under Tools. Sometimes the plugin add its own sidebar section entirely. If you can’t find the settings page, the plugin may not actually have one (check the readme file, if there is one). Or read the installation notes for the plugin.

Notice the problem? Combining concepts with tasks is really ugly. You can’t just breeze through the steps and perform the action. Minimalists would probably scream at this approach.

But what if all of the explanatory information is actually important? I could also re-arrange things a bit to de-emphasize the conceptual explanations, like this:

To install a plugin:

  1. To install a new plugin, go to the Plugins page.

    Plugins are like modules in Drupal or extensions in other programs — they add more functionality to the software. There are thousands of plugins to choose from, but keep in mind that many are created by third-party developers and are in varying states of development — some haven’t been updated for years and may no longer work with the latest version of WordPress.

  2. Click Add New.
  3. Browse to the zip file to upload it. After you upload it, activate it.
  4. Once uploaded, look for the settings page.

    Most plugins have a page under the Settings menu that provides information about configuring the plugin, including instructions on how to use it. If it’s not under Settings, try checking under Tools. Sometimes the plugin add its own sidebar section entirely. If you can’t find the settings page, the plugin may not actually have one (check the readme file, if there is one). Or read the installation notes for the plugin.

Here, I explain what plugins are in the context of the task, but I’ve pushed the concepts below the tasks so that users who want to read more can, while users who don’t need more information aren’t burdened by the explanations. This is better, but still problematic. What if my next topic is Deactivating Problematic Plugins.

To deactivate problematic plugins:

  1. Go to your Plugins page.
  2. Look for plugins that look non-standard, or that have names that you don’t recognize. Remember that many plugins are created by third-party developers and so they may be out of sync with the latest version of WordPress …. hey, I explained this in a previous task, so why am I repeating myself again?

A better approach is to start the page off by listing the main concepts:

About Plugins

Plugins are like modules in Drupal or extensions in other programs — they add more functionality to the software. There are thousands of plugins to choose from, but keep in mind that many are created by third-party developers and are in varying states of development — some haven’t been updated for years and may no longer work with the latest version of WordPress.

Plugin Settings Pages

Most plugins have a page under the Settings menu that provides information about configuring the plugin, including instructions on how to use it. If it’s not under Settings, try checking under Tools. Sometimes the plugin add its own sidebar section entirely. If you can’t find the settings page, the plugin may not actually have one (check the readme file, if there is one). Or read the installation notes for the plugin.

Install a Plugin

  1. To install a new plugin, go to the Plugins page. For more information about plugins, see About Plugins.
  2. Click Add New.
  3. Browse to the zip file to upload it. After you upload it, activate it.
  4. Once uploaded, look for the settings page. For more information about finding the Settings page, see Plugin Settings Pages.

Deactivate Problematic Plugins

  1. Go to your problematic plugins page. For more details on why plugins may have incompatibilities, see About Plugins.
  2. Click Deactivate next to unfamiliar plugin names.
  3. Using the process of elimination, keep deactivating plugins until your problem disappears.

By listing concepts first, you can streamline your task sections to avoid cluttering them up with bulky explanations that you may or may not need to repeat in later sections. You can either refer to the conceptual sections or just assume the reader can scan for the information if needed.

Because pages tend to get long, I also like to collapse sections. All the bulk above collapses in a short visual span with some jQuery magic:

[toggle title_open=”About Plugins” title_closed=”About Plugins” hide=”yes” border=”yes” style=”default” excerpt_length=”0″ read_more_text=”Read More” read_less_text=”Read Less” include_excerpt_html=”no”]Plugins are like modules in Drupal or extensions in other programs — they add more functionality to the software. There are thousands of plugins to choose from, but keep in mind that many are created by third-party developers and are in varying states of development — some haven’t been updated for years and may no longer work with the latest version of WordPress.[/toggle]

[toggle title_open=”Plugin Settings Pages” title_closed=”Plugin Settings Pages” hide=”yes” border=”yes” style=”default” excerpt_length=”0″ read_more_text=”Read More” read_less_text=”Read Less” include_excerpt_html=”no”] Most plugins have a page under the Settings menu that provides information about configuring the plugin, including instructions on how to use it. If it’s not under Settings, try checking under Tools. Sometimes the plugin add its own sidebar section entirely. If you can’t find the settings page, the plugin may not actually have one (check the readme file, if there is one). Or read the installation notes for the plugin.[/toggle]

[toggle title_open=”Install a Plugin” title_closed=”Install a Plugin” hide=”yes” border=”yes” style=”default” excerpt_length=”0″ read_more_text=”Read More” read_less_text=”Read Less” include_excerpt_html=”no”]

  1. To install a new plugin, go to the Plugins page. For more information about plugins, see About Plugins.
  2. Click Add New.
  3. Browse to the zip file to upload it. After you upload it, activate it.
  4. Once uploaded, look for the settings page. For more information about finding the Settings page, see Plugin Settings Pages.

[/toggle]

[toggle title_open=”Deactivate Problematic Plugins” title_closed=”Deactivate Problematic Plugins” hide=”yes” border=”yes” style=”default” excerpt_length=”0″ read_more_text=”Read More” read_less_text=”Read Less” include_excerpt_html=”no”]

  1. Go to your problematic plugins page. For more details on why plugins may have incompatibilities, see About Plugins.
  2. Click Deactivate next to unfamiliar plugin names.
  3. Using the process of elimination, keep deactivating plugins until your problem disappears.

[/toggle]

In order to separate concepts from tasks, I use noun phrases for concept sections and action verbs in the present tense for tasks. I don’t necessarily group all concepts first and then list tasks. Tasks that relate to concepts appear under the relevant concepts. But I generally list concepts first because the tasks rely on the concepts.

Adobe RobohelpMadcap Flare

This entry was posted in findability on by .

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, DITA, and more. If you're trying to keep up to date about the field of technical communication, subscribe to my blog.Email

10 thoughts on “How to Organize Page-Level Content

  1. chuck scott

    Tom – really great example and love how you ended this post with jQuery show / hide method … question, is that jQuery part of a WordPress Plugin that is available in wordpress.org repository or is this something you rolled yourself ..??.. i like the elegance of simple plus buttons on far right that drop down with light grey background surrounding the title header and corresponding copy … bravo :>) cordially, chuck scott

    Reply
  2. Neal

    I really like collapsible sections, but I’ve encountered some usability issues with them (searches won’t look in collapsed sections, users might not know which section contains the info that they want). It would be great if you could search for something and the search result would auto-expand the correct section, but I haven’t seen that.

    Reply
    1. June

      We have the same issue with collapsible sections. We used them on our website for precisely the reason you outline above, but we’ve been told they breach accessibility guidelines (WCAG2.0 in Australia), and using either the site-wide search, or in-page browser search, won’t bring up the term required.

      Would love to hear thoughts around how to manage detail, hide it when necessary. AND have the content fully searchable …

      Reply
      1. Tom Johnson

        June, thanks for your comment. I didn’t know WCAG2.0 recommends against collapsible sections. I’ll have to read more about that. I’ve been thinking about workarounds. I’m not really sure at this point. If I could build some logic into a script on the page, such as, “if previous page in browser history is search page, then automatically show all hidden sections” that might work. I just don’t know how to code that logic yet.

        This might be problematic, though, because it would create some unpredictability with the section behavior. Some pages on auto-load would have the sections expanded, while others would have them collapsed.

        Ideally, the logic should be, “if previous page in browser history is search page, and the section contains keyword searched for, then expand just that section.” surely that’s already coded somewhere.

        Reply
  3. Reshma

    Hi Tom –

    I’ve recently implemented the exact same thing for my Technical Guide. I use Flare and I’m doing this using drop-down text controls. I’ve added a H2 class to the drop-down head style to use for these sections.

    This guide is a mammoth legacy document with content strewn all over the place that I have undertaken to restructure. There are several topic files with a concept and a bunch of hyperlinks that a user would find it very difficult to navigate through. By consolidating information about concepts and related tasks within a single topic, I have reduced the number of topic files in my Help from 5400+ to about 4900 at last count.

    I am glad that my approach is validated by your blog post.

    regards,
    Reshma

    Reply
    1. tjohnson

      Reshma, wow, that is a monster help file. You really have about 5,000 topics? Just curious, but what’s the subject? At a certain point, navigating within such a large TOC becomes too difficult. Imagine if the reader didn’t have the TOC at all. Would he or she be able to find enough information on a single page to complete a task?

      Thanks for sharing.

      Reply
  4. Pingback: Evaluating the Usability of Collapsable Sections (or jQuery’s Content Toggle) | I'd Rather Be Writing

  5. Pingback: Evaluating the Usability of Collapsible Sections (or jQuery’s Content Toggle) » eHow TO...

  6. Pingback: Nobody Likes a Messy Web Page | RIT SMS Professional and Technical Writing

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>