Have you ever noticed that much of the online MSDN .NET framework help is.. not helpful? Take the the MSDN help for the IBindingList.AddIndex method, for example:
Fair enough; then how about some combination of the two? Editorial content combined with a bit of user content – either a linked Wiki or comments attached to the page.
In a way, we kond of have that now with our blogs. Instead of comments or linked wiki, what about an RSS filter, kind of like Memeorandum or Blogdigger? When commenting on a KB article or property/method, be sure to tag your post with the KB ID or full namespace signature (like System.Data.SqlClient.SqlConnection). That’s pretty sweet when you think about all the implications.
I’m looking for my favorite example of ‘overundocumentation’. That’s where MS did include a sample, but the sample requires about 300 lines of extraneous code to demonstrate something that could have been done in 5.
Sorry–I meant Blogniscient, not Blogdigger. Slightly different things, but both would get the job done in their own way.
As an alternative to a Wiki, projects like MySQL and PHP have user annonated manuals which work well. I like having a seperation between the “official” docs and user contributed docs.
Sometimes, the decomposition of problems into concerns make these classes look, oh so darned stupid. And you really can’t understand one without understanding all the rest.
In this case, it is better for the documentation to point to a common outline of how several classes work together, than documenting them by themselves, which makes for ridiculous reading.
Java is making some effort to reduce LOC by making common invocations simpler (I’ve blogged about this), and if the documentation pointed to these as examples, a developer would be able to quickly grasp how the classes work together.
The funny thing is that I made this same point in a comment on a post by Jeffrey Palermo pushing GhostDoc:
http://codebetter.com/blogs/jeffrey.palermo/archive/2005/11/22/134967.aspx
That Codebetter.com example is really horrible. I’m amazed that people write tools to generate totally useless documentation automatically. Have some guts and don’t bother. If a computer generates it, it’s not documentation.
On the other hand, maybe the verbose XML-like syntax made him do it. JavaDoc is a little shorter to type.
What really scares me is that tools like GhostDoc produce exactly this kind of useless undocumentation.
Now, I understand that GhostDoc is just a tool intended to assist developers in producing real documentation.
And like all tools, it can be used properly or abused
I agree completely. As the author of GhostDoc I’m responsible for a lot of crappy documentation on this world. Judging from the emails I get, there are a_lot of people who misunderstand and mis-use GhostDoc (it’s the same people who complain when GhostDoc produces garbage output from a garbage indentifier name, or expect a complete class summary from a class with name consiting of a single word).
That’s why I’ve decided long ago to never implement the often requested feature of commenting a whole file at once. That doesn’t stop people from writing a macro to do that, but my experience so far has been that people are extremely lazy (some are even amazed by the fact that GhostDoc has a configuration dialog), so by not implementing that feature there’s at least a slight chance that people take a look at the doc comment they have just created and maybe add some more details, remarks or whatever.
I think it’s telling that my other documentation-related tool “ExtractXml” (a href="http://weblogs.asp.net/rweigelt/articles/10456.aspx)"http://weblogs.asp.net/rweigelt/articles/10456.aspx)/a generated no reaction at all (ExtractXml can be used for generating examples from e.g. unit tests or other code, ensuring that the examples actually work).
Maybe I should repackage ExtractXml (or something similar, in a much more polished version) together with GhostDoc to push the idea a little more.
Take a loook at http://msdn2.microsoft.com/en-us/library/system.net.globalproxyselection.select.aspx
There’s example of how not use a proxy, but no example is provided of how to use a proxy.
Agh, I hate it!
I don’t understand. Yes, it would be better to have real documenation. But how does a stub saying, “Yes, there’s an interface IBindingList and here are its methods” hurt? If you took out the “undocumentation” how would I know the interface even exists?
I also don’t get what’s wrong with the PassportIdentity.SignOut example. It’s a static void method with one signature. That one signature takes a single argument, a string. What’s so complicated about that? Isn’t two lines of code and three lines of comments enough? Can you suggest a better example?
Well, at least we can take comfort in knowing that Sun’s Java documentation is just as crappy. It is really hard to create good API documentation without digressing into entire volumes on how to write complex systems. Many method/properties simply don’t make any sense when considered in a standalone fashion. Trying to show examples for some of these causes you to have to write a significant amount of sample code just to get the point across.
I personally prefer simple API docs that are backed up by sturdy “how-to” manuals.
I was with you 100% until the very end. Wikis aren’t documentation, either. In some cases, they’re not even undocumentation–they’re just empty.
90% of Wikis I’ve seen are total crap. Lack of formatting rules and structure makes them very unusable. Only a few have managed to become usable, and most of them have strong rules on formatting, structure etc.
Patrick: It would be better to have no example at all than to have an example that gives absolutely no context or reason to use a method. We all know that method M with parameter p on static class C is invoked by writing C.M§. The current example is just like that: it gives us no additional information whatsoever. In order for an example to be useful, it must provide some information regarding when and why to call the method. The how is a no-brainer.
I think a wiki would be a great idea, although it is unlikely to replace undocumentation completely. I can’t imagine Microsoft relinquishing control of MSDN documentation, however inadequate, in favour of a wiki.
When I encounter undoc, my next step is Google (or maybe Google Groups), and a collation of info from the resulant blogs / coding sites / discussions. A comprehensive wiki would be much more suitable.
I also don’t get what’s wrong with the PassportIdentity.SignOut example. It’s a static void method with one signature
For one thing, why in the world does the logout method required a path to an image? And is that path relative or absolute? Some context on what the heck the method actually MEANS would be nice. And a code sample with more context, eg, not just a one-liner.
Like all undocumentation, the existing documentation doesn’t tell me anything that I didn’t already know.
I was with you 100% until the very end. Wikis aren’t documentation, either. In some cases, they’re not even undocumentation–they’re just empty.
Fair enough; then how about some combination of the two? Editorial content combined with a bit of user content – either a linked Wiki or comments attached to the page.
I think VS.NET exacerbates the situation a bit. Since I always have my projects set to consider warnings as errors, I get errors when I try to generate XML docs for any undocumented public members. So what do I do? I GhostDoc them.
What I should do is stop being lazy and set up a separate build type for documentation that doesn’t break on warnings. But I hate the long wait when you switch between different builds.
All documentation should be wikis. I totally agree. They have comments but noone uses them. I am sure there are plenty of .net wikis but microsoft really is missing out not getting free docs and samples worked out on their content.
It’s interesting that microsoft has implemented the idea of “Editorial content combined with a bit of user content […] comments attached to the page.” since this article was written.
They call it ‘Community Content’. Too bad nobody use it. I think I only ever saw (interesting) user content once…
Component One’s FlexGrid for .NET is one good example of undocumentation.
When you search for a method in their undocumentation, you get 5 topics with the same name. That naturally must lead you to believe that at least one of them tells you at least something. Alas, the feeling that you’re about to waste time proves true and all five are just different versions of auto-generated undocumentations.
Their old VB FlexGrid documentation made in WinHelp for windows 3.11 is I think at least double the quality of their current hi-tech undocumentation.