Writing guidelines

1. Section, step, and note counts

Below are the maximum number of sections and steps available to create a tutorial. However, research shows that the shorter the better! 

Recommendations

• Sections: The best-performing tutorials have less than four sections. However, a tutorial can have a maximum of 10 sections.
• Steps: There should be less than five steps per section, with the desired amount of three steps. Don't put all your steps in one section!
  
• Notes: No more than two notes per step. 

Tip: For more guidance on how to write sections, steps, and notes please head to Create a tutorial > Tutorials.

Character counts

Each text field in TBW has a counter to help you keep track of character limitations.

2. Titles and descriptions

Tutorial titles

• Communicate what the tutorial is about in the title.
• Make the title SEO-friendly and searchable.
• Start the title with an action verb, not an “-ing” verb.
  • Example: Brighten a dark photo with an adjustment layer
• Avoid "How to" or "learn how to" in titles.
• If you mention product features in the title, include what the feature will be used for.
  • Example: Remove objects from a photo with the Healing Brush tool
• 120 characters with spaces is the max. Shorter is better.
• Make the title short.

Section titles

• The section title should start with an “-ing” verb (gerund) and summarize what users will accomplish by following the steps in a section.
  • Example: Refining the artwork appearance
  • We use gerunds for section titles in response to how some users read section titles as steps. Changing from a verb to a gerund helps set the right expectation.
• Don't add a period at the end of a section title.

Tutorial descriptions

• Tutorial descriptions appear under the Tutorial title on the start screen. Use it to describe what the tutorial covers and why it is useful.
• Add a period at the end of the Tutorial description.
• Example: Adjust brightness and contrast to improve a dark photo.
  

Section descriptions

• Section description appears under a section title. Use this field to convey what the user will learn in that section. Remember, shorter is better!
• Add a period at the end of a section description.
• Example: A layer mask lets you hide part of an underlying image layer without permanently changing the image layer.

3. UI elements

When creating steps, you will likely point to a specific tool, menu, or panel that helps the user complete the task. Search for it in the step text field using the "@" symbol to find and insert the relevant tool or feature.

As you type, a suggested list of tools or features will appear for you to select. Once selected, the UI name will be formatted differently from the rest of the text. This creates a coach mark, a blue box, which serves as a visual aid for users, pointing them to the correct tool or feature.

If you don't see the tool or feature you want to use, type in the name without the "@" symbol. For panel and menu commands use ">" to indicate the workflow. Use only the UI element name in the product itself. This does not create a coach mark. 

• Example: Layers > Layer Actions > Lock Layer

If you find several tools and features are unavailable using the "@" system, please let someone on the Learn Global Operations team know.

4. Terminology

The tables below contain key terms authors should know and use.  

Acronyms

Product names

Follow these guidelines when you mention a product name in a tutorial:

• Don’t include “Adobe” in the product name, unless explicitly stated in the "Do Use" column. 
• Mention Photoshop only when it’s important for clarification. 
• Don’t include “CC” in the product name. 
• If you must use a product name, stick to the names in the "Do Use" column.

Specific terminology for tutorials

Based on research and preferred terminology, there are specific word choices to use and avoid. Please review the list below, along with the reasons for these preferences. Uniform terminology fosters a coherent learning environment for our users.

5. Punctuation 

Use correct punctuation, such as placing periods at the end of descriptions, steps, and notes. Titles can be written without periods or additional punctuation.

6. Capitalization

Use sentence case capitalization in your tutorial including titles, descriptions, and steps.