How-To Task
While a regular task topic focuses on generalized guidance (for example, how to create reports), a how-to task topic provides instructions on how to go through a very specific usage scenario (for example, how to create a report that shows VMs with no restore points).
When to Use How-To Task Topic
Use this topic type in case you want to describe a sequence of steps that must be performed to complete a specific scenario.
How to Use How-To Task Topic
This topic structure consists of the following elements:
- Title — the name of a scenario.
Use a verb-based title that briefly summarizes the goal of the scenario. Make sure the verb is the first word in the title.
- Rationale — reasons for the scenario.
Identify problems that could be solved by completing the scenario. If necessary, add some conceptual background to let users better understand the context of the scenario.
Describe the goal that must be reached. However, do not reveal how to reach the goal at this point.
- [Optional] Prerequisites — limitations and prerequisites that exist for the scenario.
Specify conditions under which this scenario can be completed. For example, some scenarios become available only if there is a specific license edition installed, or if some specific infrastructure components have been deployed 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 complete the scenario.
Begin the procedure with an introductory phrase that 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, begin with navigation details and end with a screenshot. Think of the topic as of a recipe with photos; make sure to show an intermediate result at each stage. For more information, see Aligning Images with Text.
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.
Important |
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] Results — follow-up steps that exist for the procedure.
Describe expected results, add a screenshot to illustrate the results, explain if there is a way to check whether the procedure completed successfully, include examples and useful tips to support the scenario, or provide information on actions that users could do next.
If you decide to add a screenshot at this point, 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.
Example
How to Restore VM Guest OS Files (FAT, NTFS, ReFS) [title] When you recover guest OS files from Windows-based VMs, Veeam Backup & Replication mounts the content of a backup file directly to the Veeam backup server and displays the file tree in the built-in file browser. You can copy the files you need and save them locally or anywhere on the network. You can even point applications to restored files and work with these files as usual. [rationale + context] When restoring VM guest OS files, mind the following requirements and limitations: [prerequisites]
To restore guest OS files from a Microsoft Windows VM: [procedure]
At the Restore Point step of the wizard, select the necessary restore point.
At the Reason step of the wizard, specify a restore reason for future reference.
At the Summary step of the wizard, click Finish.
To verify whether the restore process completed successfully, perform the following steps: [validation]
Open the Backup Infrastructure view. In the inventory pane, select Managed Servers. In the list of managed servers, right-click the backup server and select Rescan. Wait for the rescan task to complete and close the window with the rescan results.
Open the Files view. In the inventory pane, expand the file tree under the backup server. Navigate to the C:\Restored folder and make sure it contains the restored files and folders.
|
