Omer van Kloeten's .NET Zen

Programming is life, the rest is mere details

News

Omer van Kloeten's Facebook profile

Omer has been professionally developing applications over the past 8 years, both at the IDF’s IT corps and later at the Sela Technology Center, but has had the programming bug ever since he can remember himself.
As a senior developer at NuConomy, a leading web analytics and advertising startup, he leads a wide range of technologies for its flagship products.

Get Firefox


powered by Dapper 

.NET Resources

Articles :: CodeDom

Articles :: nGineer

Culture

Projects

Console.WriteLine(1+1);

A post on DanF's weblog (via Scoble) reminded me of the thing I despise most about the MSDN: Samples for language reference.

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.

*sigh*

Comments

Chris Frazier said:

Tools -> Options -> Environment -> Help -> External Help:)
# December 5, 2003 6:13 PM

Omer van Kloeten said:

Actually, Chris, I prefer using internal help... Maybe it's just me, but it feels tidier. :)
# December 5, 2003 6:26 PM

timallen@microsoft.com said:

Omer van Kloeten,

Thank you for your comments about the .NET Framework. By taking the time to examine the documentation, you are helping us to improve the quality of our documentation and samples. Please accept our apologies for any inconvenience this may have caused you.

In particular, you mentioned that the System.Console.WriteLine sample had no sample output. Perhaps you noticed, but did not mention that the sample also doesn't seem to have the required "using" or "imports" statement, depending on your programming language.
The reason is that the samples are annotated with XML tags. The only thing that is published is the text between the tags. The using/imports statement and sample output are actually in the sample, but outside the XML tags. I've opened a bug to fix that.

With regards to formatting the samples, formatting is affected by the way the samples are published. Some of the dynamic formatting features of the .NET Framework documentation are not available in MSDN.

With regards to viewing the samples in Visual Studio, that's a harder problem. The documentation is specifically written to be viewed in the .NET Framework Help browser. Any other way of looking at the documentation is bound to suffer.

With regard to compiling and running the samples, some examples such as those that use a Windows Form, only make sense when used in Visual Studio. While other, simpler, examples could just be copied into Notepad, then compiled and run at the command line. It all depends on the sample. Perhaps the reason, after all these years, there is no universal way to compile and run samples is because different samples have different requirements.

In any case, your comments are food for thought. I assure you, many people have read and are considering them.

Tim
.Net Framework SDK User Education

(This response is provided "AS IS" with no warranties, and confers no rights.)
# December 8, 2003 8:27 PM

Omer van Kloeten said:

Tim,

Thanks for the lengthy comment and I'm glad that you guys are taking all of this into consideration. :)

If I could offer a piece of advice: It could be great if there was a highlighter for keywords in the help's code segments for better readability. It could even get the view settings from Visual Studio.NET in the integrated version and change colors accordingly...
# December 9, 2003 1:28 AM

TrackBack said:

# June 22, 2004 7:18 AM
Leave a Comment

(required) 

(required) 

(optional)

(required)