July 15, 2005
The Undocumented Framework
The Framework help is full of undocumentation. Consider the entry for the IBindingList.AddIndex method:
Adds the PropertyDescriptor to the indexes used for searching.
[Visual Basic] Sub AddIndex( _ ByVal property As PropertyDescriptor _ )
[C#] void AddIndex( PropertyDescriptor property );
[C++] void AddIndex( PropertyDescriptor* property );
[JScript] function AddIndex( property : PropertyDescriptor );
- The PropertyDescriptor to add to the indexes used for searching.
The list must support this method. However, support for this method can be a nonoperation.
Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework
This is an example where quacking like a duck doesn't make you a duck. This looks like documentation. It shows up in the help along side of documentation, it's indexed like documentation, but it's not documentation. It doesn't actually tell anyone anything they don't already know.
We all know that large swaths of the Framework are undocumented in exactly this way, and many v1.0 SDKs are, well, very undocumented.
Honestly, my problem isn't that lots of stuff is undocumented, it's that Microsoft spent time writing this undocumentation, proof-reading this undocumentation, and putting this undocumentation through the same process as the real documentation. I don't know how much time was spent undocumenting things, but I'm guessing that if you add it all up, it's a lot.
That time could have been much better spent providing better documentation elsewhere than undocumentation here.
I guess on the documentation teams, there must be some law that no class, property, method, or event will show up in the help with a big, bold, "Undocumented".
Can we stop pretending? Can you just mark everything as Undocumented until you get around to writing real documentation for it? Maybe even include a "Click here to vote to have this documented."
For a simple test, if it doesn't include a code example, it's not documented. Just mark it as such and move on.
Posted on July 15, 2005 at 10:50 AM | Permalink
I completely agree - documenting a method requires more than reiterating the arguments and return value.
The .NET framework isn't the worst offender though - there are a lot of commercial components that have this kind of 'documentation'. I think it's because Xml comments and NDoc make it so easy that people think they can produce documentation without any effort.
Well they can - the documentation looks great, but has absolutely no value. Developers need to realise that if it takes you no extra time to write, it is almost certainly useless.
Posted by: Kevin Ryall | Jul 16, 2005 5:13:26 PM
Spot on, Scott. And as Kevin points out, MS is not alone. Crappy documentation is a pervasive problem.
Funny post. Thanks.
Posted by: Peter | Nov 26, 2005 5:02:08 PM
Here here - the idea of Microsoft being honest and marking things as "undocumented" is excellent. As well as the idea of being able to vote for having it documented - good one.
I must have spent HOURS of time reading undocumentation (love the phrase, btw) to learn, well, um, nothing at all in most cases.
Posted by: Chris | Jul 15, 2006 6:21:51 AM
Note that their is a whole different class of interfaces and functions that are *officially* classified as "undocumented": The ones that are not listed in the documentation at all! Like NtCreateSection (in ntdll.dll), the raw function behind the documented CreateFileMapping.
For decades MS has strongly discouraged the use of such interfaces and functions, dating all the way back to the undocumented DOS functions described in books such as "Undocumented DOS" (By Ralf Brown, Andrew Schulman et al) and online resources such as the "Interrupt list" (edited by Ralf Brown). An IBM-sponsered book on PC-DOS (MS-DOS) 4.0 even contained an official subclassification of such APIs into 4 classes of undocumentedness.
But skeletal content-free documentation like that discussed here is a common problem, not just for programming interfaces. Look through the end-user help for many MS products, and nondocumentation turns up everywhere.
Posted by: Jakob | Nov 8, 2006 5:25:47 PM
Two new studies show why some people are more attractive for members of the opposite sex than others.
The University of Florida, Florida State University found that physically attractive people almost instantly attract the attention of the interlocutor, sobesednitsy with them, literally, it is difficult to make eye. This conclusion was reached by a series of psychological experiments, which were determined by the people who believe in sending the first seconds after the acquaintance. Here, a curious feature: single, unmarried experimental preferred to look at the guys, beauty opposite sex, and family, people most often by representatives of their sex.
The authors believe that this feature developed a behavior as a result of the evolution: a man trying to find a decent pair to acquire offspring. If this is resolved, he wondered potential rivals. Detailed information about this magazine will be published Journal of Personality and Social Psychology.
In turn, a joint study of the Rockefeller University, Rockefeller University and Duke University, Duke University in North Carolina revealed that women are perceived differently by men smell. During experiments studied the perception of women one of the ingredients of male pheromone-androstenona smell, which is contained in urine or sweat.
The results were startling: women are part of this repugnant odor, and the other part is very attractive, resembling the smell of vanilla, and the third group have not felt any smell. The authors argue that the reason is that the differences in the receptor responsible for the olfactory system, from different people are different.
It has long been proven that mammals (including human) odor is one way of attracting the attention of representatives of the opposite sex. A detailed article about the journal Nature will publish.
Posted by: Ododayvegleda | Nov 16, 2007 1:11:53 AM
The comments to this entry are closed.