Write a reference article
Start your article with a very short introduction (1 sentence). Explain the function, cmdlet, or setting and why someone would use it. When is it useful?
Start with an example
-
Get straight to a quick example of a common scenario.
Explain what's in the example: (use italics to format variables or parameters).
Optionally, add a screenshot for context (if UI is hard to locate, or it’s needed to complete the task).
Maximum width: 520 pixels. Use a standard theme, do not show any personal information, and crop to show only what's relevant.
-
(Optional) Add another example and explain how it works differently.
If you want to highlight the tasks where this reference would come in handy, add an inline link.
Target no more than 500 words for an article. Optimize for in-app help and mobile viewing. In Chrome, you can use F12 to see how an article will appear on mobile.
Add links to "relatedTopics" section below to highlight related content.
(Optional) Provide best practices or special cases
What are the best practices for using this function, cmdlet, or setting?
Use a table if you have to list values or parameters - but rely more on giving people great examples to copy than listing choices they have to put together themselves.
|
Value or parameter name |
Explanation |
Example |
|
Use helpful column headers. |
Keep it short and specific. |
Include examples to help them get on the right path. |
(Optional) Address common problems and how to troubleshoot them
What can go wrong? How do they figure out what's going wrong? How do they fix it? Where else can they go to get help?
You can use a table to list issues people might come across and how to address them, or include links to troubleshooting, support, or community resources.
|
Problem |
What went wrong |
How to fix it |
|
Use helpful column headers. |
Keep it short and specific. |
Include examples to help them get on the right path. |