[Ai] Writing Sections, Steps and Notes

Let your voice and style shine through as you write your tutorial. Please avoid language that might be perceived as promotional or ’fluff.’

Guidelines for writing Sections, Steps and Notes

All tutorials you create in the Illustrator Tutorial Builder, are composed of Sections, Steps, and Notes. It’s your job to determine how to organize the content so that the tutorial is broken into bite-size pieces called sections. 

Each Section contains a series of Steps and sometimes Notes. We want to avoid continuing Steps from one Section to another (unless the Section needs to be continued). All Steps are numbered. A Note is not numbered, but rather supporting information for a numbered Step. 

Some information will need to be entered manually rather than via recording it. Always use Placement > Canvas to add a numbered Step manually. 

When writing Steps make sure you edit for clarity and are concise. We don’t want the user to scroll in order to read all the Steps in a Section. Additionally, large blocks of text fatigue users. Edit to keep users interested, engaged, and following the tutorial. 

Example: If you were creating a tutorial on working with shapes in AI, the sections might be: 

• Creating a shape
• Editing that shape
• Rounding corners
• Adding other shapes
• Assembling the _______
• Combining shapes

Start each step with an action verb that tells users what to do

• DO example: Click the Plus icon to add to the selection.
• DON’T example: If the tool didn’t select the entire object, click the Plus icon to add to the selection.

Include approximate values in steps

• Include an “about” value for each slider or numerical field you ask the user to change
• DO example: Drag the Clarity slider to about +20 to increase contrast in the midtones.

Include the “why” in steps

• Kinds of “why” to include:
  • The outcome of an instruction 
  • Reasons to use a particular workflow or tool
• Examples:
  • Outcome of the instruction:
    • DO example: Drag the Opacity slider to about 80 to make the artwork more transparent.
    • DO example: Increase brush Size to about 50 so the brush is slightly bigger than the spot
    • DON’T example: Drag the Opacity slider to about 80.
  • Reasons to use a particular workflow or use a particular tool:
    • DO example: Drag out a text box for paragraph text. Paragraph text, which reflows within its box, is useful when you have a lot of text to add.

Use Notes to accommodate some of the why

• If a step doesn’t have room for some critical “why,” consider following the initial step with a note that offers the why without an action. But use notes sparingly, since we want to keep the user engaged with clicking through the tutorial.
  • DO example:
    • Step: Click the Locate Object icon in the Layers panel.
    • Note: The selected content in the document is revealed in the Layers panel.
• Don’t include suggestions for alternative workflows, particularly in beginner tutorials.
  • DON’T example: Another way to add an adjustment layer is to go to the Adjustments panel and click the icon for that adjustment layer.