Windows Confidential: In Triplicate, Please?

It’s simply not possible to write a formal document detailing every possible action, whether it’s a good idea or not.

Raymond Chen

A customer once observed that the size of a file as reported by Explorer didn’t change until the application that was updating the file finally closed the file. (There was more to the issue, but we’ll leave it at that.)

The customer liaison found a blog entry of mine on the subject, but asked around to see if there was any formal documentation. It isn’t clear what sort of formal documentation he was looking for to resolve this issue.

The nature of non-contractual behavior is that it tends to not be formally documented. Formal documentation creates the impression that the non-contractual documentation is indeed contractual. “What do you mean you changed the behavior under condition X? I have this document from you that says that under these conditions, the behavior is Y. In Windows 7, though, you changed the behavior to Z. Windows is no longer behaving as documented.”

The customer liaison asked if we could create a Knowledge Base article based on my blog entry. “The customer is insistent on an official document so they can include it as part of their product documentation,” he said.

Making it official documentation, however, would defeat the whole purpose of having explicitly non-contractual behavior. One colleague remarked, “Formal documentation is not the same thing as customer-ready. Perhaps they’re polar opposites.”

A blog entry is like an informal conversation you have with somebody at a conference, or when you run into someone at a local sporting event. But because it’s a blog entry, it’s an informal conversation with a few thousand people. This informal conversation might give you some insight into an issue and help you understand it better, but it’s hardly formal documentation.

A Web search for the four keywords “file,” “time,” “update” and “MSDN” turned up documentation on MSDN that stated: “Timestamps are updated at various times and for various reasons. The only guarantee about a file timestamp is that the file time is correctly reflected when the handle that makes the change is closed.”

So there’s your formal documentation: It says nothing specific about what happens, aside from the one contractual behavior—namely that the information is correct when the handle is closed.

My colleague Aaron Margosis frequently gets requests from customers for documentation that explicitly says that a bad idea is a bad idea. For example, one customer liaison wrote, “My customer uses .reg files to deploy Group Policy settings, instead of using Group Policy Objects (GPOs). I’m trying to get them to switch, but they’re looking for a formal document explaining why their current model is a bad idea.”

The answer to the specific question is that manual .reg files have all sorts of problems. They’ll conflict with the domain Group Policy. Manual .reg files won’t be able to take advantage of existing tools for managing Group Policy, such as the Group Policy Editor or the LocalGPO utility that comes with the Security Compliance Manager.

Determining the result of applying multiple .reg files can be difficult if their settings overlap and conflict. You won’t be able to use a tool like Resulting Set of Policy to study all applicable settings and determine the final result. You won’t be able to search for a GPO to locate the ones that affect a particular setting.

Furthermore, changes applied by manual .reg files often don’t take effect until the next logon. All you’re really doing is updating registry entries without notifying the relevant components that a setting was changed and they should go check the new setting. As a result, any settings you apply are always one step behind.

These are the things that might go into this hypothetical, “Why using .reg files to deploy policy is a bad idea” white paper. As Aaron explained it, “There are an infinite number of places where you can choose between doing the smart thing and the dumb thing, but only a finite number of white papers documenting those instances.”

For example, do you really need a formal document that says, “If you’re prompted to restart the computer after you install a Microsoft security update, make sure that you immediately perform the restart operation?” This seems obvious, but a customer once insisted that we create such a formal document before they would be dissuaded from having a company policy of installing security updates and then not restarting the system.

Most of these demands for formal documentation come not from people who are unable to apply common sense to a situation, but rather from people who are unwilling to put their own neck on the line for a decision and want to pass the buck. While it’s true this is a technique to avoid getting fired, it’s also a technique to avoid getting promoted.

Raymond Chen

Raymond Chen's Web site, The Old New Thing, and identically titled book (Addison-Wesley, 2007) deal with Windows history, Win32 programming and negative anniversaries.