Recording Tutorials

From K-3D

Overview

K-3D's interactive tutorial system works by recording user interaction with the program, in a form that can be "played back" by users to learn new concepts. The K-3D team records tutorials (albeit slowly) that become part of the official K-3D distribution - you can contribute to that effort, or you can record tutorials to share with friends / students / co-workers on your own. Tutorials can be easily recorded, shared electronically, and played-back.

How To

Start Recording

Choose Scripting > Record Tutorial ... from the menu to open the Tutorial Recorder. Recording is already turned-on when the Tutorial Recorder opens, so you can start working with K-3D immediately and your actions will be automatically recorded:

Record a Message

To record a Message that will be displayed to the user when your tutorial is played-back, type your message in the space provided at the top of the Tutorial Recorder and hit the Record Message button. The message will be displayed just as a user would see it in the Main Document Window. The mouse pointer moves to the Continue button, which you must press before you can continue recording.

Highlight UI Widgets

To draw the user's attention to ("highlight") part of the user interface, use the Tutorial Recorder Tools > Command Node Inspector menu item to open the Command Node Inspector:

Double-click the left mouse button on an entry in the Command Node Inspector to highlight it, and the highlighting action is automatically recorded along with the rest of your tutorial.

Note that not all entries in the Command Node Inspector can be highlighted.

Correct an Error

If you make a mistake while recording, hit the Tutorial Recorder Stop button to stop recording. The "Recording in Progress" message disappears and you can see the recorded tutorial text. You can manually edit the contents of the tutorial, removing your mistake. Don't forget to undo any corresponding changes in the K-3D document, then hit the Record button to continue.

Finish Recording

Once the tutorial is completely recorded, hit the Tutorial Recorder Stop button and use the File > Save menu item to save the tutorial. If your tutorial is intended to become part of the official K-3D distribution, save the tutorial to the k3d/share/tutorials directory, then edit the k3d/share/tutorials/index.k3d file, adding an entry for your new tutorial. The next time you open the Tutorial Menu, your new tutorial will appear, ready for use.

Edit Existing Tutorials

You can load previously-recorded tutorials into the Tutorial Editor, either for manual editing or further recording - new recording is always appended to the end of the tutorial.

Use Different Script Languages

K-3D tutorials are normally recorded using the K3DScript engine. K3DScript records tutorials using a simple, compact XML-like file format that does not depend on any external script engines or libraries, which makes it ideal for the majority of scripts. You can also record scripts using the Python engine, which encodes tutorials into the Python language. This can be useful if you wish to create "smart" tutorials that contain their own logic, e.g: to alter the tutorial content based on the current platform or whether a particular plugin is available.

By default, the Tutorial Recorder uses the K3DScript engine, to use a different script engine use the Tutorial Recorder Tools > Script Language menu to pick the script engine you want. Note that changing the script engine starts a new tutorial from scratch - you cannot mix different script engines within the same tutorial.

Style Guidelines

• Every tutorial should create a new document prior to making changes. Rationale: this ensures that the tutorial does not modify the user's work in any existing documents. It also ensures that the newly-created document window will have the default panel layout instead of any user-customized layout that could break the tutorial during playback.
• Every tutorial should delete the document(s) it creates prior to closing, and reopen the Tutorial Menu. Rationale: this returns the workspace to the configuration it was in before the tutorial was run, and leads the user in a natural way to the next tutorial.