Last updated on
27 December 2021
Let your voice and style shine through as you write your tutorial. Please avoid language that might be perceived as promotional or ’fluff.’
Writing coach marks
- Start each coach mark with an action verb that tells end users what to do
- Do example: Shift+drag on the image to add to the selection.
- Don’t example: To add to the selection, Shift+drag on the image.
- Don’t example: If the tool didn’t select everything, Shift+drag to add to the selection.
- Include approximate values in coach marks
- Do example: Drag the Clarity slider to about +20 to increase contrast in the midtones.
- Do example: Drag the Opacity slider to around 40% to reduce layer opacity.
- Include the “why” in coach marks
- Kinds of “why” to include in coach marks:
- The outcome of an instruction
- Do example: Set brush Size to about 50 so the brush is slightly bigger than the spot.
- Don’t example: Set brush Size to about 50.
- A reason to use a particular workflow
- Do example: Drag out a text box for paragraph text. Paragraph text is useful when you have a lot of text to add.
- A workaround for a current limitation of Tutorial Builder
- Do example: Select the Brush tool. If this tool is already selected, click another tool and then click back on the Brush tool.
- Tip: Include this workaround only the first time the first tool is used in a tutorial. It is not necessary to repeat this for other tools in the same tutorial.
- Non-action coach marks can be added to accommodate some of the why
- If an action coach mark doesn’t have room for some critical “why,” you can follow it with another coach mark that offers the why without an action.
- But use non-action coach marks sparingly, since we want to keep the user engaged with clicking through the tutorial.
- Example:
- Initial action coach mark: Click the Add Adjustment Layer icon and choose Brightness/Contrast.
- Followed by non-action coach mark: Notice the new Brightness/Contrast adjustment layer in the Layers panel. Editing on an adjustment layer protects the image layers below from permanent changes.
- Automatic feature bolding in coach mark text: This applies only for names of panels and tool bar items.
- When you enter the name of a panel or an item from the tool bar in ca oach mark text, type an @ symbol and choose the name of the item from the dropdown feature menu that appears. This will bold the feature name in the text.
- If you don’t see the feature you want to use, type the feature name without the @ symbol.
Note:
Use Notes only for critical troubleshooting
Add a Note to a step only if there is a “gotcha” a user is likely to experience on that step.
Writing Notes
- Notes appear in the end user’s panel. However, Notes can distract end users’ attention from coach marks. So keep notes to a minimum.
- Don’t add more than 2 Notes per Section.
- Write “Tip” at the beginning of each note.
- Don’t use Notes for instructions, alternative ways of doing something in Photoshop, keyboard shortcuts, or to explain the “why” of a step.
- Do example: Tip: If the Brush tool doesn’t paint at full strength, go to the Options bar and make sure Opacity and Flow are both set to 100%.
- Automatic feature bolding in Note text: This is the same as for coach mark text and applies only for names of panels and tool bar items.
- When you enter in Note text, the name of a panel, or an item from the tool bar; type an @ symbol and choose the name of that item from the dropdown feature menu that appears. This will bold the feature name in the text.
- If you don’t see the feature you want to use, type the feature name without the @ symbol.