Search results

How to Organize Page-Level Content

by Tom Johnson on Mar 16, 2013
categories: findability

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.

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.