A task topic describes a sequence of steps that must be performed to achieve a particular result.
Mind the following differences:
For example, performing backup is a task required to create a copy of production data.
For example, creating a backup job is an activity required to perform backup.
For example, creating a backup job involves a number of steps to be taken. You must select VMs to back up, define the VM backup order, specify backup storage settings and so on.
For example, backup is a job-driven process: to perform backup, you must configure backup jobs; a backup job is a configuration unit of the backup activity.
When to Use Task Topic
Use this topic type in the following cases:
- If you want to provide instructions on how to perform an operation.
- If you want to guide users through a specific usage scenario.
- If you want to describe a procedure in which each step represents a separate task topic.
If a task topic describes a complex procedure, add a concept topic to support the task topic. A procedure is considered to be complex if one or more of the following conditions are met:
How to Use Task Topic
This topic structure consists of the following elements:
- Title — the name of an operation.
Use a verb-based title (as opposed to a noun-based title for a concept topic) that briefly outlines the operation. Make sure the verb is the first word in the title.
If an operation can be performed for only one object of a kind, use the singular form for the object noun (for example, Installing License). If an operation can be performed for multiple objects, use the plural form for the object noun (for example, Deleting Files).
- Rationale — reasons for the operation.
Explain why it is important to perform this operation. Provide enough context to understand the operation; the context must connect user goals with solution workflows.
Organize content into paragraphs and subsections.
- [Optional] Warnings — possible outcomes of the operation.
If the result of an operation affects users in any way, clarify the consequences before proceeding to the operation. To draw attention, use notes.
For example, consider a situation where a user goes through a configuration wizard to edit job settings. If all currently running jobs will be stopped as soon as the user completes the wizard and clicks Finish, you must warn the user about that.
- [Optional] Prerequisites — limitations and prerequisites that exist for the operation.
Specify conditions under which this operation can be performed. For example, some operations become available only if there is a specific license edition installed or if some other operations have already been performed beforehand.
Do not dive too deep into details. For example, do not list system requirements — this is what the System Requirements section is for.
- Procedure — a sequence of steps required to perform the operation.
Begin the procedure with an introductory phrase that describes the procedure goal, starts with an infinitive and ends with a colon. A period at the end of the lead-in phrase is also acceptable. If the procedure applies to multiple objects (for example, if a user can modify and delete a set of objects using the same procedure), clarify that in the introductory phrase.
Use a numbered list to show the order in which procedure steps must be performed. Each step must describe a particular action and begin with navigation details. If a step is optional, mark it with the [Optional] tag, and place the tag at the beginning of the step. Do not add software responses and supplementary details as separate steps — depending on the context, include this information in the currently or next executed step as List Paragraph.
In Veeam documentation, we do not instruct users to click Next when proceeding to the next step of a wizard. Instead, we begin each topic that describes a particular step with the name of that step. For example, At the Virtual Machines step of the wizard, select VMs and VM containers that you want to back up.
The maximum number of levels in a nested procedure is 3. If a procedure requires more than 3 levels, consider restructuring the procedure and adding subsections. In this case, each subsection must have a title that briefly summarizes the step and starts with Step #.
- [Optional] Post-requisites — follow-up steps that exist for the operation.
Describe expected results, explain if there is a way to check whether the operation completed successfully, include examples and useful tips to support the operation, or provide information on actions that users could do next.
- Screenshot — an illustration of the operation.
If there is only one screenshot that illustrates the operation, place it at the end of the topic. Do not leave important details and notes after the screenshot — users tend to skip such information, especially when they read documents online and have to scroll further to notice it. For more information, see Aligning Images with Text.
- [Optional] Links — links to related concept and task topics.
As task topics are usually related to hypothetical situations and their consequences (such as user actions and the particular results of these actions), you can use the simple future tense and first conditional sentences when describing procedures and usage scenarios. For more information on verb tenses that we use in Veeam technical documentation, see Plain English.
Creating Lab Groups [title]
In most cases, a VM does not work in isolation but has dependencies on other services and components, such as Microsoft Active Directory or DNS. To verify such a VM, the DataLab will have to supply all services this VM is dependent on. For this purpose, VAO uses lab groups. [rationale]
To create a lab group for a DataLab: [procedure]
For a DataLab to be displayed in the DataLabs list, it must be included into the list of plan components available for the scope, as described in section Configuring Veeam Availability Orchestrator.
Related Topics [links]