Partager via

Tips for Troubleshooting by Using the Documentation

  • Article

My previous post recommended that you use the documentation to help you resolve problems with Configuration Manager 2007. But the Configuration Manager documentation library contains a lot of information, and it would be unrealistic to read every topic, every word. So what’s the most efficient way to use the documentation to help resolve problems you run into when you're using Configuration Manager? Here’s my suggested top 10 tips for a documentation solution that could save you a lot of time and frustration in trying to track down a problem.

Note: Many of these solutions involve using search, which is easy enough if you’re using the help file (SMSv4.chm) that ships with the product. However, if you’re using the online Web version, searching so that returned entries are relevant only to Configuration Manager is more challenging – but can be done. See How to more easily search the Configuration Manager documentation library online.

 

1. Something doesn’t work even though you’re sure you have configured it correctly

 

Documentation solution: Check that you’re not missing one or more prerequisites for the product/feature. I know we’ve said this repeatedly, but we’re still seeing customer issues because prerequisites were missing or customers are trying to configure an unsupported scenario. Search for “prerequisites for <feature name>”. More information: Getting To Know Your Dependencies.

Also check the Readme file in case there was something important that wasn’t known at the time when we handed off the documentation.

 

2. Clarification for an option in the UI – what it does and the ramifications of configuring it

 

Documentation solution: In the UI, press F1 or click the Help button for context-sensitive help. Even the wizards have help, although they don't display a Help button (press F1 instead, or use search).

 

We worked hard to drive more useful help into the F1 help, but it’s difficult for us to know if customers use this or whether it’s actually helpful. Most customers will use the F1 help that comes with the product rather than use the online Web version so we have less feedback for these topics than we do other topics – for example, how often customers read these topics and how they rate them for quality/accuracy.

My recommendation is to use the F1 help that comes with the product, and if it doesn’t answer your question, copy the exact topic title to search for the online version to check for any updates. If the online version doesn’t answer your question, send an e-mail to SMSDocs@Microsoft.com with details.

3. Procedural information - how to configure something

 

Documentation solution: Search the documentation using “How to” and then include key terms. If you’re not sure what the key terms are, browse the table of contents that relate the area you’re configuring.

For example, if you’re trying to find out how to configure something related to a specific feature, locate the topic level topic for the feature under Configuration Manager 2007 Features, and then drill down into the Configuring <full feature name> chapter for one-off tasks relating to configuring the feature, and Tasks for <full feature name> chapter for everyday tasks that you might use for the feature.

 

If you’re looking for something that affects the whole site rather than a specific feature, browse through Planning and Deploying the Server Infrastructure for Configuration Manager 2007 to find the best location – for example, whether it’s something that affects every site, or multiple sites, or Internet-based client management sites.

4. Explanation for a specific term, acronym, or icon

 

Documentation solution: Use the glossary for terminology specific to Configuration Manager. If it’s terminology outside the product, use a general Web search. If it’s an icon in the Configuration Manager console that you’re having problems interpreting, use the icon glossary.

5. Supporting information about an underlying product feature or concept

 

Documentation solution: Configuration Manager is a very complex product and configuring it is very challenging because there are so many building blocks that have to be in place before you can even begin to start configuring a single feature. For example, we’ve seen problems with configuring software updates because of a lack of understanding about collections, software distribution failing as a result of incorrectly configured packages, and one of the most common problems for new administrators is client push when discovery or boundaries are not configured correctly.

For a basic grounding, see Fundamentals of Configuration Manager 2007 and be prepared to do some homework on basic features such as boundaries, discovery, collections, queries, inventory, reporting, and how to use the Configuration Manager console.

Even if you are a seasoned administrator for SMS 2003, some of the changes in the new version can trip you up, so be sure to check out What's New in Configuration Manager 2007. For example, we still see customers with site assignment problems after upgrading from SMS 2003 because they are unaware of the new client deployment check for site compatibility.

6. Technical details for understanding how something works - for design decisions or troubleshooting help

 

Documentation solution: Most of the conceptual information is in topics that have a title “About” and then the key terms. You can browse for these in the table of contents under Overview of <feature name> , search for key terms, or use the suggested links in how to topics or F1 topics.

Additionally, search for “flowchart” if you’re looking for technical process detail, and “Log files for” if you’re looking to step through each process to help troubleshoot where something fails.

And keep an eye out for more SuperFlows when they are published!

7. Roadmap or guidance for what needs to be configured and in what order to achieve an end-to-end solution

 

Documentation solution: Search for the following:

  • “Administrator checklist”
  • “Administrator workflow”
  • “Example scenario” and “Example scenarios”

8. Gotchas and commonly reported Issues

 

Documentation solution: Use the troubleshooting documentation. This information actually appears twice in the library – in the context of configuring the site or feature, and for easy access we’ve also pulled it together into a troubleshooting chapter, Troubleshooting Configuration Manager 2007. It is the same information, so you don’t have to check in both places.

If you search or navigate the troubleshooting information that relates to the area you need, you might find a single topic that lists commonly reported issues (for example, Troubleshooting Software Distribution Issues) or multiple topics that identify distinct areas (for example, Troubleshooting Configuration Manager Client Issues is split into 5 distinct areas). The common issues topics contain a number of different issues so you won’t necessarily find your problem with a search on the topic title – you have to scroll through the issues topics and check each section. However, these topics do support expand and collapse, so if you know that the issue isn’t relevant you can collapse the section to more easily read through the rest of the topic.

And if you want to be proactive about identifying gotchas before they get you, check out the separately published quizzes. These focus on the need-to-know facts that can become gotchas if you’re not aware of them.

9. Corner cases and less commonly reported issues

The product documentation cannot document every single variation and combination but does aim to address at least 80% of customers. For corner cases and less commonly reported issues, search the knowledge base (https://support.microsoft.com/search). The hits for these are monitored so if we find that many customers are referencing them, we look to include them into the product documentation.

10. Configuring an external technology – such as PKI, SQL, ISA …

Expect the product documentation to explain how to design, configure, and help troubleshoot Configuration Manager - but not how to design, configure or troubleshooting a dependency that is external to the product. In these scenarios, use any of the following methods to bridge the technologies:

  • Relevant product documentation
  • Web searches
  • Community resources
  • Relevant training
  • External expertise such as consultancy services
  • Hiring staff with relevant skills and experience

We always want to help our customers, but there is a limit to how much we can – and should - document something that’s external to our product. More information: see the myITforum article A Day in the Life of a Technical Writer - What's In and What's Not.

 

 

- Carol Bailey

This posting is provided “AS IS” with no warranties and confers no rights.

Comments