Tim Anderson's ITWriting

June 7, 2006

Annoying documentation

I came across the following documentation in Visual Studio's online help, when puzzling over the Advanced Compile Options dialog:

Generate serialization assemblies
Select Off, On, or Auto from the drop-down list. Off specifies that serialization assemblies not be generated. On specifies that serialization assemblies be generated. By default, this option is set to Auto.

This gem conveys zero additional information, beyond what you can already see in the dialog. The reason I looked up help was that I wanted to know what Auto means in this context. I'd also like to know where the assemblies are generated, and what if any additional steps I need to take in order to deploy them with my project and avoid the cost of generating them at runtime.

Time for some research I guess. This blog entry is a start, if you are wondering why you should care.

Still, my main point is about documentation. I see plenty of entries of this kind - actually, Microsoft is not the worst offender; Borland is much worse.

It is high time Microsoft and others implemented online help with a comment facility as in PHP.

Tags: visualstudio microsoft onlinehelp