Cheat sheet authoring guidelines

Cheat sheets and composite cheat sheets enable a user to achieve a goal by completing a sequence of steps. These guidelines discuss when to use cheat sheets and how to best write a cheat sheet.

When to create cheat sheets

Cheat sheets are well suited to tasks which consist of steps which lead towards a tangible goal, such as building a simple application. The goal must be well defined so that the user can see success when all the steps in cheat sheet have been completed. Tutorials are often good candidates for cheat sheets, in a tutorial the goal is to learn how to perform a specific task. Cheat sheets will usually contain up to 10 steps and can be completed in a half an hour or less. For larger tasks consider using a composite cheat sheet.

When to create composite cheat sheets

Composite cheat sheets are used to for providing guidance through a task which is too large to describe in a single cheat sheet or which has multiple goals. A composite cheat sheet can be used to describe a sequence of tasks each of which builds on its predecessor.

When not to use cheat sheets

Cheat sheets work best when problem can be solved by a sequence of simple steps. Cheat sheets are not a substitute for the help system which allows for creation of HTML pages with rich graphics and random access of information using search and hyperlinks. Cheat sheets are not intended for tasks which require a large amount of text to be input by the user.

Guidelines for creating a cheat sheet

Choose a short and meaningful title.
Utilize links to the help system in cheat sheet tasks whenever possible to provide background or more detailed information
Consider rewriting as a composite cheat sheet if there are more than 10 steps.
Utilize commands where possible to perform simple tedious tasks such as opening perspectives, opening resources, executing wizards. Be sure to also provide a description of how to achieve the same effect without using the command.
Ensure commands can be skipped if the user decides to do the steps manually
Specify dialog="true" for steps which open dialogs. This will cause the cheat sheet to open in a "tray" to the right of most dialogs.
Organize the steps in such a way that the user sees visible signs of success frequently. A cheat sheet that makes a number of different changes to java source and then launches an application could be rewritten so that the application was launched after each source change.
Make sure the user understands why they are performing each step.
Rather than describing multiple ways to perform a step pick the simplest way requiring the least amount of description.
Use break (<br/>) tags to improve readability.
Subitems can be used to break steps down into smaller steps.
Not all cheat sheets will require subitems.
Start subitem label text using action word such as "Input", "Expand", "Select", etc
For subitem labels, clearly identify interface text using quotes to allow users to differentiate instruction text from interface text they need to locate and interact with.
Each subitem should be responsible for one atomic task such as inputting one value.
Always add an <onCompletion> element to the last step of a cheat sheet.
Test cheat sheets with different sizes for the cheat sheet view.
Test cheat sheets with the error log view open so you can see if any warnings are written to the log.

Guidelines for creating a composite cheat sheet

A composite cheat sheet should contain tasks that are related by a common theme.
Each task within a composite cheat sheet should have a well defined goal.
Use <onCompletion> elements to recognize success.
Task names should be short and concise.
Complex problems can be solved by using tasks that build upon their predecessors.
Use skip="true" if a task is optional.
For consistency, make sure the simple cheat sheet introduction and name match the introduction and name specified in the composite cheat sheet..
For task descriptions, clearly identify interface text using bold formatting.
Sequences should be used only when it is important to enforce order in which tasks can be started.