Mike van der Meulen's Blog

OK, this is probably not very informative, but I have to complain about the state of today's documentation, in particular, Microsoft's documentation.

We see tons of new technologies produced by Microsoft (and others), and published, tweeted, blogged about all over. Focusing just on the .NET "stuff", the amount of documentation is huge, but the quality is abysmal.

C#, VB.NET has had XML Comment Tags for nearly a decade now:

''' 

''' Returns the number of times Counter was called.
''' 
''' Number of times Counter was called.
Public ReadOnly Property Counter() As Integer
    Get
        counterValue += 1
        Return counterValue
    End Get
End Property

We have had tools like SandCastle also for years.

Before these tools became available, documentation had to be written from scratch, often the developers would collaborate with a tech-writer and produce documentation like this http://msdn.microsoft.com/en-us/library/ms682425(v=vs.85).aspx. This example is from the Win32 API documentation. It looks fairly complete, the purpose of the function is clearly explained, all parameters have explanations and the Remarks section offers additional usage information.

One would expect that tools like XML Comment Tags and SandCastle would tremendously improve documentation. The documentation can now be automatically generated based on comments the developer leaves with the source code. The formatting and presentation can still be controlled by tech-writers.

Unfortunately human nature (or laziness) prevails and we end up with decent looking, completely unusable documentation.

Case in point, here was an apparently particularly lazy programmer at work or he/she assumed everyone is a mind reader:

http://msdn.microsoft.com/en-us/library/system.web.webpages.scope.scopestorage(v=VS.99).aspx

As of 1/26/2011 it is impossible to find out what the purpose of the ScopeStorage class is. This class happens to be used in MVC 3 (a released feature), so I have to assume @haacked, @scottgu, et. al., somehow found out what the purpose of the class is - probably some form of internal Microsoft-only mind meld. In this simple, small class the purpose can be derived from the MVC 3 source. It handles web.config <appSetting>. It sure would be nice if the documentation actually mentioned that.

No matter how good your product, code or API is, if we can't find out what it does, how to use it or that it's even available, you might as well save your time and not develop it. If our only source of documentation is someone else's source code, a blog or a tweet, it's useless.