Documentation Redesign Informal User Test Notes

Owned by Jonathan Hung
Last updated: Apr 11, 2011Version comment
3 min read

Test Setup

Testing was based on a version of the Progress API page design. Users were asked to give their impressions of the layout, structure, and content of the page.

  • User 1: Beginner Javascript and Infusion user.
  • User 2: Beginner Javascript and Infusion user.
  • User 3: Experienced Javascript and Infusion user.

Before each walkthrough, users were told that the design is not a complete API page, but enough API content is shown to give a general impression of the design.

Summary

Navigation

Facilitate navigation of contents

  • 2 users expected a table of contents or some sort of way of navigating within a page.
  • 2 users suggested the left-navigation give links to top-level headers, or a ToC
  • 1 user suggested to put function names in the left nav (i.e. Javadoc style).

Design, Layout, Typography

Inconsistency in Values in Options section

  • "strings" Values section is good, but possible values (i.e. "ariaBusyText" and "ariaDoneText") needs to stand out a bit more.
  • Too much reading to be done in Values. List it out or make it easier to pick out needed info.

Content updates "news" needs to be distinct

  • Pages with "Updated News" type content
  • Not distinguishable enough. Use bullets, or combine into 1 para
  • link to the affected area in API
  • Any recent updates, major change in distinguishable colour instead of brown?

UI Options - unclear function

  • Not sure if it allows changing of layout, in addition to fonts, colours, and sizes.

Edit button

  • 1 user remarked on the Edit button.
  • Thought UI Options and Edit did the same thing due to proximity.

Page Content

Desire for Illustration or Demo

  • User 1: Up top: link to the demo, or something to show it.
    • screen shot, or a demo.
    • link not as desirable since they want the content up front.

More Examples

  • Each section should help the user get from A to B
  • i.e. in the Events section, specifying the events isn't enough. Need a code snippit to show how it can be used.
  • Possible solution: more examples (2 users wanted to see more), or links to more examples and demos.
  • User 1 really likes the "Examples" line in the creator, would like to see it included in other sections.
  • User 2 specifically sought out examples in the API page
  • One user suggested ability to hide examples if they're too long.
  • should we provide links to demo? in example?

More Descriptions

  • Each section should have a short description.
  • i.e. "Creating a Progress Bar" is missing a description. Couldn't quite figure out the creator section right away - needed to read the table to find out.
  • make it more explicit.

Define Foreign Terminology

  • Not sure what "Type" means or what a "Default" event type is (especially when most events are "Default").

Specify what parameters are truly optional and which are required

  • i.e. in Methods section, not sure what is optional or required for a function.

Option information inline with Methods

  • Would be useful to see the option information inline with parameters so you don't have to scroll.
    • User 1 feels that Selectors should go inline with Methods.

Need better word for "Default" line in Selectors section

  • Not clear what "Default" is. Needs to be more context appropriate.
  • Try: "Default Classname", "Default Selector Name"

API layout generally good

  • generally good overall. The row headers are easy to read, even though thing are inconsistent from section to section.

reorganize so content goes from more general to more specific

  • Possible structure:
  1. Overview
  2. Creator
  3. Events
  4. Methods
  5. Options
  6. Selectors

Community contributed content

  • comments from users/developers at the bottom generally helps (not always)
  • Example: drupal.org.
  • Community contributes examples, code, comments, support for others. This content eventually gets incorporated into API page if appropriate.

Versioned Tech Docs

  • One user suggested the ability to change version of document so you are seeing what is applicable only to a version of Infusion.
  • i.e. Select from Infusion 1.2 and 1.3 etc. This saves having to report deprecation and "Availability" information.
  • Example implementation: Drupal's API docs http://api.drupal.org/api/drupal/includes--form.inc/group/form_api/7

Examples of API pages