Tutorial guidelines

From Gamewiki

For people making game design tutorials here are some guidelines.

Screen Dumps

Screen dumps are essential to show the users what to expect.

• use a tool to create create screen dumps (e.g., SnapZ on the Mac)
• only show necessary context. If you talk about a specific rule consider only showing that one rule and not the entire behavior editor including the rule
• stay consistent with visual presentations, e.g., use drop shadows for ALL windows and no drop shadows for ALL selections. For instance, with SnapZ, use Border: Normal Window setting to get drop shadows when snapping "Objects..."; but avoid drop shadows with Border: none with "Selection..."
• do not resize screen snaps but do use image thumbs to reduce the size of large window if they do not contain a lot of important detail. For instance, there is no need to show a large empty worksheet 1:1
• naming: keep in mind that all images are share across the entire wiki. Do not create image names specific to an article such as "figure2". Make image names descriptive and keep them general so that other articles could use the image as well. Instead of "Figure13" name the image "DepictionEditorShowingFrog"
• wiki image markup manual

Dealing with Repetition

Many tutorials include repetitive instructions. For instance, in AgentSheets users need to create agents all the time. The first time you may want to keep the steps pretty explicit showing the windows involved and explaining the steps to be taken. Later in the tutorial you may wan to just say something like "now create a truck agent." Ideally, you create or use an article talking about how to create an agent. Your markup could look something like this:

Now [[how_to_make_an_agent|create a red truck agent]]

turning into: Now create a red truck agent

Do not worry if the article does not exist yet. This is the way wikis work.

Writing Style

Use a consistent writing style. For instance the The Apple Publication Style Guide defines how to name objects, and how to describe human interactions. Example:

click Use click to describe the act of positioning the pointer on an object onscreen and briefly pressing and releasing the mouse button. Don’t use click on. (You don’t click the mouse button, you press and release it.) Because most users know what clicking is, you need to define it only in documentation designed for beginning users, such as tutorials.

• Icon: To open the Mail application, click the Mail icon in the Dock.
• Button: To show the toolbar, click the Toolbar button in the top-right corner of the window.
• Disc icon: Click the disc icon, and then choose File > Make Alias.
• Unnamed elements: In the photo viewing area, click the disclosure triangle next to the film roll you want to view.