| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css"> |
| <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> |
| <title>Cheat sheet authoring guidelines</title> |
| </head> |
| <body> |
| |
| <h2>Cheat sheet authoring guidelines</h2> |
| |
| <p> |
| 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. </p> |
| |
| <h3> |
| When to create cheat sheets</h3> |
| |
| <p> |
| 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. </p> |
| |
| <h3> |
| When to create composite cheat sheets</h3> |
| |
| <p> |
| 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. </p> |
| |
| <h3> |
| When not to use cheat sheets</h3> |
| |
| <p> |
| 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. </p> |
| <h3>Guidelines for creating a cheat sheet</h3> |
| <ul> |
| <li>Choose a short and meaningful title.</li> |
| <li>Utilize links to the help system in cheat sheet tasks whenever possible to |
| provide background or more detailed information</li> |
| <li>Consider rewriting as a composite cheat sheet if there are more than 10 |
| steps.</li> |
| <li>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.</li> |
| <li> Ensure commands can be skipped if the user decides to do the steps |
| manually</li> |
| <li>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.</li> |
| <li>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.</li> |
| <li>Make sure the user understands why they are performing each step.</li> |
| <li>Rather than describing multiple ways to perform a step pick the |
| simplest way requiring the least amount of description.</li> |
| <li>Use break (<br/>) tags to improve readability.</li> |
| <li>Subitems can be used to break steps down into smaller steps.</li> |
| <li>Not all cheat sheets will require subitems.</li> |
| <li>Start subitem label text using action word such as "Input", "Expand", |
| "Select", etc</li> |
| <li>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.</li> |
| <li>Each subitem should be responsible for one atomic task such as inputting |
| one value.</li> |
| <li>Always add an <onCompletion> element to the last step of a cheat sheet.</li> |
| <li>Test cheat sheets with different sizes for the cheat sheet view.</li> |
| <li>Test cheat sheets with the error log view open so you can see if any |
| warnings are written to the log.</li> |
| </ul> |
| <h3>Guidelines for creating a composite cheat sheet</h3> |
| <ul> |
| <li>A composite cheat sheet should contain tasks that are related by a common |
| theme.</li> |
| <li>Each task within a composite cheat sheet should have a well defined goal.</li> |
| <li>Use <onCompletion> elements to recognize success.</li> |
| <li>Task names should be short and concise.</li> |
| <li>Complex problems can be solved by using tasks that build upon their |
| predecessors.</li> |
| <li>Use skip="true" if a task is optional.</li> |
| <li>For consistency, make sure the simple cheat sheet introduction and name |
| match the introduction and name specified in the composite cheat sheet..</li> |
| <li>For task descriptions, clearly identify interface text using bold |
| formatting.</li> |
| <li>Sequences should be used only when it is important to enforce order in |
| which tasks can be started.</li> |
| </ul> |
| |
| <h3>Related links</h3> |
| <p> |
| <a href="../../org.eclipse.platform.doc.user/reference/ref-cheatsheets.htm">Working with cheat sheets</a><br> |
| <a href="../../org.eclipse.platform.doc.user/reference/ref-composite-cheatsheets.htm">Working with composite cheat sheets</a><br> |
| <a href="ua_cheatsheet_simple.htm">Simple cheat sheets</a><br> |
| <a href="ua_cheatsheet_composite.htm">Composite cheat sheets</a><br> |
| </p> |
| |
| </body> |
| </html> |
