Best practices for writing quick starts

Author: Katie Edwards | Last edit: December 02, 2024

Quick starts are guided tutorials that open in a side panel in a user interface. They contain step-by-step instructions for completing a specific task in a short amount of time. 

In the Hybrid Cloud Console, for example, you access quick starts from the Learning Resources page for the related service bundle. In on-premise versions of software such as OpenShift Container Platform, a quick start is embedded in the product’s user interface. Quick starts are ideal for walking a user through a new feature or an unfamiliar user interface. They’re especially useful for getting up and running with a product. By the end of a quick start, the user should have successfully achieved the goal specified at the beginning of a quick start. Often this takes the form of a usable “artifact,” like a running instance or working configuration. The user can then continue to use the product or feature, or begin another quick start.

This guidance is based on the quick start conventions in the quick start YAML template. Use this template to structure and create your quick start.

Key findings from Red Hat user research studies on quick starts are captured in What we know about the usability of quick start guides at Red Hat. To access this document, log in to EnjoyHQ with your Red Hat email. 

Style considerations

Like all our product documentation, quick start writing follows the tenets of Minimalism. However, quick starts can use a more conversational, informal tone than our official product documentation. Aim for the “fairly conversational” style, which is authoritative but more encouraging and approachable than our usual formal, less conversational tone.

To achieve a more conversational tone, try the following:

• Use the second person (“you”) to directly address the reader.
  • Example: “In minutes, you can set dates, document your first user story, assign a task or two, and dive into the code.
• Stick to shorter, simpler sentences, and keep content minimal; avoid creating a wall of text that might overwhelm the user.
• Avoid unnecessary technical jargon, and define terms and phrases that might be unfamiliar to new users. Quick start content should be intuitive. 
• Use contractions (you’ll, can’t, you’ve) to strike an informal tone, and to save space.
• Avoid sentence fragments, poor grammar, and excessive punctuation, which can distract from the task.
• Always keep in mind that the content must be appropriate for a global audience.

Though quick starts can be more informal than our standard documentation, they must also be opinionated and to the point. Quick start writing should be concise and relevant to the task. Extraneous information can distract the user from completing the prescribed task.

Whenever possible, help the user stay in the quick start by including the information the user needs, and avoiding links that take the user away from the quick start task. If you do need to include more contextual or technical information, you can provide carefully curated links within the task, or at the end of the quick start.

For more style resources, see Additional resources at the end of this guide.

UXD research findings

The UXD research team has conducted multiple studies on the usability of quick starts, and summarized the findings of those studies in What we know about the usability of quick start guides at Red Hat. This feedback, gathered from real users, should be top-of-mind when writing quick start content. 

Key considerations:

• Users can become overwhelmed by the amount of information that quick starts provide. Keep the scope of the quick start small, and provide simple, concise steps.
• Technical jargon and wording that is specific to a particular product, or that requires background knowledge and experience using a respective platform, can be confusing to some users. Use intuitive language, and explain terms or phrases where necessary. 

Structure

A quick start primarily consists of tasks and steps. An individual quick start can have one or multiple well-defined tasks, where each task has multiple steps. Think of a task as a procedure in technical documentation. On the card description, also include an estimate of how long the quick start will take to complete. If appropriate, include a verification step at the end so that the user can ensure the task was successful.

A quick start follows these guidelines:

• 3-5 minutes in duration (maximum 10 minutes)
• Maximum 5 tasks
• 2-7 steps per task (maximum 10 steps), which walk the user through the UI to complete the goal of the task.

Note: While the absolute maximum number of steps is 10, user research findings suggest using 7 as the upper limit. If this number is exceeded, consider minimizing the scope of the guide.

Writing card descriptions

A quick start card contains the following elements: 

• Title
• Description of the goal that the quick start helps the user accomplish
• Estimate of how long the quick start takes to complete  

Title: 

The title (or display name) briefly identifies the function that the quick start accomplishes. Avoid using the phrase “how to,” and instead begin titles with -ing verbs.

Examples of -ing verbs: completing, accessing, submitting, adding, removing, creating and launching. 

Description: 

A card’s description is a statement that clarifies the information in the card’s title. Begin the description with an action verb. Card descriptions are limited to 3 lines or 115 characters, but text wrapping can cause the description to truncate before reaching the character limit. Verify that the quick start description is not truncated in the UI (you can preview your card by using the quick starts preview tool).

Examples of action verbs:  Complete, Submit, Download, and Remove.

Prerequisites:

List prerequisites in bullets as complete sentences; avoid phrasing them as a question to the user. Include the permissions needed to complete the tasks, and anything that must be pre-configured before starting the quick start.

See Prerequisites for guidance.

Writing content for quick starts

Introduction: 

 A quick start introduction provides a concise and informative description of what the quick start accomplishes. A long introduction can overwhelm the user. Keep the introduction to  a maximum of 4-5 sentences.

When you indicate an action, be sure to frame it as an action the user will take. Write about what the user will do, not about the quick start itself.  For example, instead of “This quick start will teach you BLANK”, write “You will complete BLANK action in this quick start”. This way, you’re foregrounding what the user will accomplish by following the quick start. 

Tasks:

Quick starts are organized into tasks, which are high-level objectives users complete to accomplish the quick start’s overall goal. Task components include the title, description, failed task help, and a summary. 

Task title: 

Each individual task must have a title. When naming a specific task, the title reflects what it accomplishes. Write the title as a statement (rather than a “how to” tutorial). Each title should begin with an action verb that indicates the specific action the task completes, followed by the title of the product it concerns. This includes verbs such as: Connect, Save, Remove, Create, Launch, etc. 

Task description: 

In the task description, explain the importance of the task for the user. When writing a task description, begin with a call to action, or a statement that identifies a desired action or outcome.

Following the call to action, write a brief statement that both explains how the user will accomplish the task and introduces the task’s steps. Keep your product terminology capitalization consistent. 

Steps:

Steps are a sequenced list of actions to guide the user through completing a larger task. Make the steps concise and easy to follow.

Begin your procedure where the user is when they access the quick start in the user interface. For example, you don’t need to instruct the user to log into the tool, because they are already logged in and interacting with the quick start.

When writing individual steps, use the word “click” to  refer to buttons and labels, and use “select” to refer to check-boxes, drop-down menus, and radio buttons. When writing task steps, remember to clearly distinguish between a user action and additional information on product functionality.

Instructions: 

Instructions refers to a line in the  quick start template that allows the user to verify if they’ve completed the task successfully. Remember to clearly distinguish between a user action and additional information on product functionality. They are written as a question, and users should be given context to how it relates back to the task at hand. For example, before asking a user if they see something on their screen, you should ask “To verify that you have ______: do you see_____?” 

Failed task help: 

Failed task help refers to a line in the quick start template where you can add a failed task message. The text you enter here  alerts a user to an incomplete or failed portion of their task. A failed task notification can simply say, “This task is not verified yet. Try the task again.” You can use this message as-is (it’s included by default in the quick start template) or edit it to include more context for the user if necessary.

Summary: 

Quick starts have two potential Task summaries: Success or Failure. You can  either congratulate the user on completing their task, or notify the user that something is impeding their completion and to try again.

For a successful summary, write a short sentence that tells the user that they have finished their task. It is best to use the personal pronoun ‘you’ in these statements. Congratulating the user is great!

For a failed summary, notify the user that their task failed, and encourage them to try the task again. Contrary to the successful-task summary, avoid using the personal pronoun ‘you,’ because it places unnecessary blame on the user.  If possible, provide the user with a brief suggestion as to why their task may not have succeeded, or a suggestion as to what they can check if it continues to fail.

Additional resources

• PatternFly UX writing guide
• PatternFly quick start YAML template
• What we know about the usability of quick start guides at Red Hat
• IBM Style
• Red Hat supplementary style guide for product documentation
• Content types: Interactive quick start [Internal only]