Contributing to TLGs Part 3: Writing a troubleshooting TLG

  • Article

A third way that you can contribute to Microsoft Test Lab Guides (TLGs) is to publish a troubleshooting TLG in the TechNet Wiki. A troubleshooting TLG contains the following sections:

  • The troubleshooting tools for the technology or feature and how they appear in a working test lab.

    This sets the stage for using these tools later in the TLG and for identifying deltas between the display of these tools when everything works and when it doesn't.

  • A set of troubleshooting scenarios, which break the functionality of the test lab in a specific way, demonstrate the broken functionality, then take you through the troubleshooting methodology to determine the root cause and correct it.

    These troubleshooting scenarios are a lot of fun because you can create a common issue and guide the reader through its resolution, in essence training them for the real thing in the wild. You can also get creative and break the functionality in ways that produce misleading error messages or conditions. Then take the reader through the troubleshooting methodology to expose the hidden culprit, giving them additional practice with the tools and troubleshooting methodology.

For example, the Test Lab Guide: Troubleshoot DirectAccess contains the following sections:

  • DirectAccess Troubleshooting Tools

    A quick listing of the UI and command line tools that are the most helpful in gathering information about DirectAccess configuration and behavior.

  • DirectAccess Troubleshooting Tools in the Test Lab

    The results of the DirectAccess troubleshooting tools on the Corpnet, Internet, and Homenet subnets.

  • Troubleshooting DirectAccess Client Connectivity Problems

    A set of five troubleshooting scenarios for common problems with DirectAccess functionality, including the following:

    • Cannot resolve intranet FQDNs (root cause 1)
    • Cannot resolve intranet FQDNs (root cause 2)
    • Cannot access a specific intranet resource
    • DirectAccess client cannot correctly detect the intranet
    • DirectAccess client cannot complete an IP-HTTPS-based connection

The process for publishing your own troubleshooting TLG is the following:

  1. Determine the test lab environment for your troubleshooting TLG

    This should be the Base Configuration test lab or the test lab based on another modular TLG.

  2. Create the content and publish

    Use the Wiki: Troubleshooting Test Lab Guide Template in the TechNet Wiki as a starting point. If you use this template, your troubleshooting TLG will have the same structure and boilerplate text as other published troubleshooting TLGs, allowing readers to more easily learn the troubleshooting tools and techniques based on your instructions.

    After documenting the tools and the troubleshooting scenarios (the steps and verifying that they work), publish the troubleshooting TLG as a single topic in the TechNet Wiki.

  3. Tell the world

    To make sure that others in the community know about your troubleshooting TLG, do the following:

    • Update the Test Lab Guides TechNet Wiki topic with a link to your new troubleshooting TLG in the "Troubleshooting TLGs" section.
    • If there is a TechNet Wiki portal page for the test lab (for example, DirectAccess Test Lab for Windows Server 2008 R2), update it with a link to your new troubleshooting TLG.
    • Send a quick email to tlgfb@microsoft.com. Tom Shinder or I will announce your new troubleshooting TLG in the Test Lab Guides blog, in Twitter, and on Facebook.
    • Advertise your new creation using your own social media outlets.

 

Write on!

 

Joe Davies
Principal Writer
Windows Server Information Experience