Documentation: One difference between us and them

Lately I have been working on a project with a number of consultants from a local linux/java company. While we go tit for tat on the arguments of Microsoft vs. Linux, they tend to be pretty honest about the fact that their opinions of Redmond are rooted in NT4 experiences. Furthermore any subsequent understandings they have of the monopolistic big brother beast who seeks to squash all other companies comes from the tainted threads of Slashdot.

One concession I have been able to get from these guys is this: Microsoft has great documentation and they make great tools. Of course they follow this with the Stallman worshipper talking point of the day, “…but that don’t matter cuz the OS is chock full of security vulnerabilities” – which of course ignores the facts…but then again these are emotional disestablishmentarianst zealots to whom truth does not really matter.

I say all that because it does raise an interesting point, Microsoft produces an abundance of excellent documentation. MSDN just makes every other developer resource/portal look like a second class citizen in the developer community.

This leads me to question why the community (in general) does not produce more documentation. I have recently been using an excellent .NET charting component that generated wonderful results and excellent customer reaction. BUT the documentation that came with this small component was dismal at best. Even the most popular of windows forms add-ins; DotNetMagic is absent good documentation (OK, so they have a few examples).

Now I don’t believe in leaning on docs as some sort of crunch but I have to believe the C# team is with me on the importance of this one. By adding the XML comment syntax to the language they affirmed that this is a very important element of the development process and one that should be elevated to a stature that puts it in line with syntactical tokens.

VS.NET can produce documentation for the developer provided they build it into their code and there are also some excellent open source tools to facilitate the same. NDoc, is an excellent tool that makes it easier to provide developers with API documentation of the caliber and professionalism that we see from Redmond. So why again do we see such dismal effort on the part of tools vendors and others who write the code that the majority of developers invoke?  How can we fix this fact?

I don’t know, you tell me! Or better yet, tell MSFT!

I would love to see XML comments added to VB.NET as an inherent language element. I would love to see some tools as part of Whidbey that allow make it easier to produce quality doc! I wish Redmond would find a way to embrace the community sites and blogs and integrate them into relevant documentation. Numerous people post tips on their blog like this and this. It would be great if MSDN would crawl these and link to them when relevant.

My wish is that the .NET development community will seize on documentation as a rallying point to prove to the tech world that .NET will win the battle with Java not merely by the might of Microsoft but by the superiority of our ideas and methods. Good documentation as a fundamental principal is a small part of that.

OK…Ranting complete.