Documentation Writers' Toolkit Structure Topic types Task

Task topic

Task topics include numbered steps that describe how to achieve an outcome.

Task structure

A task topic includes the following elements:

• Topic title: Write a task topic title that combines a verb and an object.

• Introduction: Provide an introduction that explains why the end user should care about the task.

  There might be conceptual material in this section of a task topic. Limit conceptual information to only what’s relevant to the task at hand.

  If you find yourself writing a long introduction, consider creating a concept topic, and then writing a shorter form of that concept in the task introduction. You can link to the longer concept topic from this introduction.

• Before you begin: (optional) Add links to tasks that need to be completed before the current one. The links might sometimes be unrelated to the product, such as “Have this thing at hand”.

  Additionally, this section can include decisions the user should make or permissions they need to confirm before starting the task.

  If there are no prerequisites, don’t include this section.

• Steps heading: The steps heading indicates that the steps are about to begin.

• Stem sentence: The stem sentence introduces the steps.

  Use the following convention when you write a stem sentence: To <NAME OF TASK>, follow these steps: For example: To create a dashboard, follow these steps:

  For more information about stem sentences, refer to Procedures in the Google developer documentation style guide.

• Steps: Users are provided with a directive through numbered steps.

  Write steps so that they contain one action, or possibly two related actions, such as Copy and paste a value or Save and quit the program.

  A step must instruct the reader to perform a specific task.

Write a task topic

To write a task, follow these steps:

1. Determine where you want to add task documentation to the Grafana Labs product documentation.

2. Create a child directory within the parent directory that follows this naming convention:

   • The directory name should include a verb and an object.
   • Use lowercase letters.
   • Add a hyphen between words.

3. Create an index.md file within the task directory.

4. Add front matter to the index file.

   For more information about front matter, refer to Front matter.

5. Add the content to a copy of the Task template.

Task topic examples

Refer to the following topics for task topic examples:

• Create a service account
• Create an organization
• Create a dashboard

Task template

When you are ready to write, make a copy of the Task template and add your content.

When to combine tasks into a single topic

In some cases, task topics are standalone and don’t contain any other content. Other times, multiple task topics can be combined into a single Markdown file. By combining tasks into a single topic, the table of contents entities can be reduced in number, which reduces scrolling and clicking for users.

When combining multiple topics into one, follow these guidelines:

• When you document more than one approach to accomplishing the same user goal.

  In the Assign RBAC roles topic, a user can use the user interface or provisioning to assign roles. There is no need to create two task topic files in this case.

• When tasks are likely to be completed around the same time.

  Users might find it useful to have all task documentation available on the same page if they’re likely to complete a number of tasks simultaneously.

  In the Data source management topic, it’s likely that an Admin user will enable permissions immediately after adding a data source.

• When you document CRUD operations.

  Create, read, update, and delete tasks can be combined into one topic. The Manage organizations topic includes tasks such as viewing, creating, editing, and deleting organizations all under the umbrella topic title of Manage.

• When you document a user workflow.

  Combine tasks when the user should start at the beginning, complete the first task, and then complete the remaining tasks in sequence.

  In Activate a Grafana Enterprise license from AWS Marketplace on EKS, the user is guided through all the tasks necessary to activate their license.