How It Works

A How It Works (HIW) topic provides very specific low-level details on a process or operation.

When to Use HIW Topic

Use this topic type in the following cases only:

• If you want to explain what happens under the hood when a particular process runs or an operation is performed.
• If a process running in the background affects users in any way, and you want to draw attention to and explicitly describe the consequences.

If a process does not affect users, or a deep dive into the process will not add much to the overall comprehension, an HIW topic is not required.

How to Use HIW Topic

This topic structure consists of the following elements:

1. Title — the name of a process or operation.

Use a title that contains the name of the process or operation. Make sure the keyword is the first word in the title or is placed as close as possible to the beginning of the title.

Do not use ambiguous titles, such as How It Works — this could confuse users in case the topic has a parent topic with a complicated title that mentions multiple concepts. For example, consider a situation where you have a parent topic named Restore to Microsoft Azure and you want to add a child topic to it. If you name the child topic How It Works instead of How Restore to Microsoft Azure Works, this could cause a misunderstanding regarding whether you were talking about how restore works or how Microsoft Azure works.

2. Lead-in — the minimum amount of details required to explain the process or operation.
3. Description — a step-by-step description of the process or operation.

Include a sequence of actions that take place as part of the process or operation. Use a numbered list to structure this sequence; each step in the sequence must define one particular action.

To describe each action, use active voice and specify its subject (that is, the initiator) whenever possible — it is important that users understand who or what performs the action, and whether any user response is required. Use passive voice only in case the subject is unknown. For more information, see Active Voice.

4. [Optional yet highly recommended] Diagram — an illustration of the process or operation.

Add a diagram to illustrate the step-by-step description. Note that if you draw numbers that demonstrate the sequence of operations, make sure these numbers match the ordered items in the step-by-step description. For example, if a description includes 5 steps, you must draw 5 numbers in the diagram — one for each step.

5. [Optional] Details — further information.

Introduce additional details that may help users understand the process or operation better.

Example