|
|
After the customer reports, "It doesn't work," you should try to figure out what the product thought it was doing at the time. If your product creates debugging logs as described in Chapter 5, then ask the customer to send them to you. Is there anything in the Windows event logs that might help diagnose the bug? Ask for those, too. Does your product write anything interesting to the Windows registry (such as stored user preferences or configuration information)? Then you probably need to see that exported registry section. If your product uses a database, then is there any "main" table you'd be especially interested in viewing? You'd probably ask the customer for an export of that table, too. All that information may not solve every bug, but it will take care of the simple ones and be an excellent start against the rest.
There's one catch, though: Most customers consider it a burden to gather that data. Most customers are non-technical and don't even know what the registry is, let alone how to export from it. Even navigating the file explorer to get to the Logs directory is a significant challenge for many of them. Microsoft's recommended standard is for each product to write its logs in a directory like "C:\Program Files\Your Company Name\Your Product Name\Logs", and that seems logical to programmers like you and me. But I hope you realize how long it would take a smart but non-technical person (say, your mother) to find a file there without help. Especially since the Windows file explorer makes it look like the Program Files directory is empty unless you read the fine print and click the "Yes, I know what I'm doing" button.
Asking your customers for all that information will force your technical support department to painstakingly walk customers through each step, and even then customers will still somehow mess it up by forgetting to send you one of the things you wanted. Then you'll have to ask again for that missing file, which will just annoy both you and your customers. But worst of all, every customer will answer only a certain number of questions or do a certain number of tests before she gets frustrated. After that, the "Why can't you just fix it?!?" attitude sets in and progress will slow to a crawl. You want to get as much information as you can without crossing that line. Therefore, instead of asking users to manually send you the data, it's good to give them a utility to automate the process. This is called an automated diagnostic utility.
As time permits, you can make your diagnostic utility more and more complex, maybe even eventually giving it the ability to walk the customer through basic troubleshooting steps. But the first version is much, much simpler. All it needs to do is gather basic logs, registry information, etc., and copy all that to a single directory. The idea is to automatically put everything the user was supposed to collect in one place to make it easier for the user to e-mail the information to you. In fact, you may want to have your utility automatically compress all those files and e-mail them to you without the user having to do anything, although we'll discuss some downside to that in a minute.
Command line interfaces are simply not acceptable for non-technical users, so your utility does need a GUI, but it can be extremely simple, with very few options. If customers look at your utility and wonder "Should I select this option or not?" then you've defeated the purpose of your utility. In particular, you shouldn't give the user such choices as "Do you want to collect registry information? Do you want to collect product logging? Do you want to collect this other information?" The utility should automatically collect it all! Your users have no idea what information you need to diagnose the bug, so why bother them with a choice they won't understand? That's just begging customers to select the wrong things, and then you'll have to call them back and ask them to send you the information again.
The information your utility gathers will depend on what you need to debug. Product logs are a must. For a Windows Service, the event logs are great to have since they tell you if and why your service failed to start. Any configuration information stored in the registry or the Active Directory or the user's profile folder may be helpful. It's also a good idea to include the version of your product, and maybe the version of any other .NET assemblies that your product depends on. When in doubt, though, err on the side of gathering more information than you need rather than less. Also, remember rule 5 from Chapter 2. Try debugging problems on a few computers without using anything other than what the diagnostic utility gathers. If you find it difficult, then maybe your utility needs to collect more information.
I designed my first diagnostic utility to automatically e-mail the files to my company's technical support department. The user clicked a single button and then we had everything we needed to diagnose the problem. Most users appreciated the convenience, but a few preferred to examine the data before sending it to us. Some customers feared we might read their private information for marketing purposes. Others felt their event logs contained confidential data. So a better strategy for the diagnostic utility would be to copy all the files into a single directory and then stop. Next the GUI could ask the user whether she wanted to automatically send the data to your company, or else allow the customer to manually send the files after examining them.
| Note |
The .NET Framework makes gathering data from the registry or the event logs or a database easy. But the one thing that Microsoft left out is a compression class. Unfortunately, there is nothing in the .NET library to help you compress multiple files into a single ZIP file. Fortunately, though, a quick web search will turn up several freely available classes for file compression. |
A diagnostic utility won't help with exotic configuration bugs, such as the Password Policy bug I described earlier. If you thought to gather information about exotic stuff in your diagnostic utility, then you probably would have remembered to handle that case in your product, too. For those bugs, you'll still need to ask the customer lots of questions. But a diagnostic utility is a great way to gather all the basic data so you have a head start on those difficult issues. It will give you reams of valuable data in one shot without exceeding the customer's "Why can't you just fix it?!?" tolerance.
|
|