I’m glad that the person who sat down and wrote the documentation took the time to write a short sample showing how to use the language element (thank you; I try to do that too in my own line of work), but some of the samples lack in several departments, such as actually explaining what they do and why.
I do not want to open a new instance of Visual Studio.NET 2003 (yes, I do know about Snippet Compiler, which is quite helpful, but I don’t use it), every time I browse for documentation. Not to mention the Windows Forms samples that, at times, require you to actually build a form with the ‘helpful’ “this sample assumes you have, on your form, a TextBox names Bernard, a GroupBox named Zachary and a full implementation of the Towers of Hanoi puzzle” comments at the beginning.
Even the simplest of examples don’t show an output at times (exempli gratia)… Quite ridiculous, and I assume you would agree.
Another thing one might consider is that the good people over at Microsoft would consider formatting their code (all it takes is a simple Ctrl+A, Ctrl+K, Ctrl+F combination, mind you) or at least using their own naming conventions guidelines…
The example escapes me, but once I even saw documentation for a method with the sample excluding the actual documented method itself.