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
- 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
- Ensure commands can be skipped if the user decides to do the steps
- 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",
- 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
- 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
- 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
- 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
- Sequences should be used only when it is important to enforce order in
which tasks can be started.
Working with cheat sheets
Working with composite cheat sheets
Simple cheat sheets
Composite cheat sheets