Most documentation is best/good done by just writing down essentials step by step. But, especially for users of graphical userinterfaces, this often is not good enough. E.g. the instruction press the xyz toolbar button doesn't help too much, when there are many toolbar buttons with non obvious symbols. Hovering over 15 buttons to see their tooltip is annoying. Some images might help. But sometimes there is only one really good way: having an animated tutorial, showing essential mouse clicks, keyboard input and progress of the GUI.
Wink is a Freeware application helping us here (running on Windows and Linux). It creates Flash films, easy to follow. So download it, capture some operation to be documented and publish ... wait.
A good Wink tutorial/documentation is more than just capture/publish! Some essential hints follow.
As the tutorial is to be shown in a web browser and in this Wiki you can't just capture your whole desktop in 2048x1536. Users would have to scroll while the animation is running. Rules to follow are:
only capture the essential part, often just some part of the GUI application, sometimes only the GUI window. E.g. when documenting Gallery 2 usage nobody wants to know, which browser you are using: capture only the client area. On the other hand, when e.g. documenting SVN handling, the whole GUI application (Explorer/Eclipse/...) has to be shown, as menus have to be opened etc.
when capturing a whole GUI window, try to size it as small as possible, 640x480 or smaller. The absolute maximum is 800x600 to avoid scrolling for (most) users.
make your life easier by sizing the GUI windows exactly to the pixel: 800x600, 640x480 ... Wink shows you the capture size.
Capture Process
Wink has 3 modes of capturing: timed, by mouse/keyboard event and manually. For Gallery and getting/working with/modifying it, the timed capture isn't appropriate at all. The event mode might be a good start sometimes, but most often isn't: it records some events/frames you later have to remove as unimportant, but more seriously, it misses some events essential to a good tutorial. E.g. it misses popup of tooltips, as no mouse/keyboard event happens. Same for the popup of submenus.
The best way to capture is the manual mode, where you press the hotkey (Pause) on every step to be documented. That key doesn't interrupt the GUI to document (popups/menus remain open and are thus captured).
Please capture once before a click and then after the click. Try to capture essential popups/submenus, when they appear on hovering. Don't move the mouse (too much) between before/after.
Capture mouse movements start and end (this is most often done anyway if you follow the rule above: capture before/after click).
Sometimes the cursor shape changes, when moving (pointer to cursor or vice versa, etc). If the target location has the same cursor shape as the start location just ignore that, the movement is the essential part. But when the target cursor is different, try to capture the shape change. Cursor change IS a valuable feedback to the user.
On long running actions, e.g. a CVS/SVN checkout capture just about 3-5 frames. Try to get 1-2 more frames near the start and another 1-2 near the end. Later you can edit/drop unneccessary frames.
Before actually capturing for production, play the planned capture through in the real application step by step. You might be surprised, how often e.g. (context) menus reach out of your captured area.
Best practice is, to place the captured area bottom left of your desktop. Thus all context menus pop up from desktop bottom up/right (your milage may vary).
If your (context) menus stick out often consider to just reduce your screen resolution while capturing. Most operating systems then fall back to some sort of making the menus available anyway. After the capture reset your screen to your liking.
Before the production capture set up / reset your GUI application to the state a new user will see.
Editing the Capture
Not editing a capture and publishing it 'as is' is considered bad. What will a user see? Often not much, except that the doc provider was able to do it. The user had to replay the turorial completely over and over again to grasp things done nearer to the end of the animated tutorial.
Buttons:
Wink has navigation buttons (next/prev/goto). The tutorial will stop in frames having a navigation button giving the user a chance to see what happened.
Use buttons in important capture frames.
The user also may do the step in parallel in the real application documented.
Always use both - next and prev - buttons together and place them near each other. The user then easily can just replay the last (few) step(s).
Put the navigation buttons always in the same locations so the user hasn't to move his mouse when clicking forward through the tutorial. Use copy/paste the button(s) in Wink or the button position input fields.
A good place for the navigation is often top right near the title bar close icon.
Callouts:
Wink has text callouts (bubbles).
Use callouts to document the steps taken.
Use callouts mainly in frames having navigation buttons to give the user a chance to read and understand the text.
You may copy/paste a callout into several frames after a button frame. The callout will be visible while the mouse moves.
On the first frame put a callout explaining what the tutorial will document.
On the last frame put a callout (green) with a success feedback.
Cursor:
Wink automatically plays animated cursor movements. Wink captures the mouse as an editable object. Edit the cursor where neccesary.
When you forgot to capture an important cursor shape change duplicate the start frame. In the later duplicate choose the target cursor and correct the mouse position to where the shape change would have occurred.
When you want to indicate a click, doubleclick or right click you may use self made special cursor shapes (see below). Duplicate the frame where the click occurs, in the duplicate change the cursor to your self made one and set the display time to 0.3-0.5 seconds.
Double clicks, right clicks and clicks with some modifier key pressed often need a documenting callout and either a button or a long display time before the click.
Resources
Here are some additional resources you may use freely when creating Wink tutorials.
Download:
Wink_resources.zip. Inspect, then copy into your Wink folder and unzip with paths (stupid WinZip)! It will add 9 new callouts and 3 new cursors. See the preview.
