About

I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 30 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

Blog Search


(Supports AND)

Google Ads

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

Quote

I would have to say that most instructions I come across are unimportant and some are harmful. Most instructions I get about software development process, I would say, would be harmful if I believed them and followed them. Most software process instructions I encounter are fairy tales, both in the sense of being made up and in the sense of being cartoonish. Some things that look like instructions, such as "do not try this at home" or "take out the safety card and follow along," are not properly instructions at all, they are really just ritual phrases uttered to dispel the evil spirits of legal liability.

James Bach



Navigation





<October 2014>
SMTWTFS
2829301234
567891011
12131415161718
19202122232425
2627282930311
2345678

Categories

  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  

Contact

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 10/16/2014

Totals
Posts - 2312
Comments - 2502
Hits - 1,674,829

Averages
Entries/day - 0.56
Comments/entry - 1.08
Hits/day - 405

Updated every 30 minutes. Last: 6:21 AM Pacific


  02:37 PM

An ignominious appearance on the DailyWTF recently got one of our documentation topics some undue attention. Alas. The topic in question pertains to what around here we call an "internal only" type or member. Or as is stated more formally, it's a topic about a class that "supports the .NET Framework infrastructure and is not intended to be used directly from your code." This is boilerplate, and many topics feature this fascinating information. In this particular case, tho, and for reasons not entirely clear, someone added the text "This type does nothing meaningful." Result: mockery. Ouch.



Couple of things here. First and most general, why do topics like this even exist? They obviously have very little useful information. Scott Swigart once memorably called this sort of thing "undocumentation." (This would be amusing, other than that I don't think Scott was particularly amused at the time.)

The short answer is: because they must. We are obligated to have at least some documentation (or undocumentation, if you will) for every single type and member that is not explicitly set to private. To put it another way, if you can use .NET reflection to see that a member exists, we have to have something in the docs for it. Why? Well, think back on history and imagine the consequences if we didn't mention it. In fact, the topic is a good example. The member exists because it's used internally. If we didn't doc it (undoc it), some folks might think that we are deliberately hiding information -- and especially that we're hiding information to which the infrastructure developers are privy. You get the picture, I believe.

No one likes this stuff. Customers don't like it. (Bob Grommes once pleaded with us not to create this stuff.) We sure don't like it. Having to deal with this sort of less-than-useful doc at all is overhead to us.

It can be argued that if we're going to generate this stuff, we could at least do a better job of it. In theory, yes. In practice ... maybe. Back in 2005 (2.0 release! -- 2 releases go), Charles Petzold totted up the APIs for the .NET Framework and came up with this:
Tabulating only MSCORLIB.DLL and those assemblies that begin with word the "System", we have over 5,000 public classes that include over 45,000 public methods and 15,000 public properties, not counting those methods and properties that are inherited and not overridden. A book that simply listed the names, return values, and arguments of these methods and properties, one per line, would be about a thousand pages long.
Doing a little scratchpad calculating, assuming we spent 1 hour per member, we'd be looking at about 60,000 man-hours (30 man-years) to doc the whole lot. Plus editing, reviewing, proofing, translating. Hopefully you'd agree that the ultimately finite resources we have are not that usefully spent on documenting APIs that you can't even really use in your code.

Our priority is instead on topics for types and members that we think are actually useful. We base this on our own judgment and on guidance from program managers et al. We also look at customer feedback on MSDN: topics that our stats tell us are heavily used are the best candidates for fixes. (Use those ratings and comments, folks!)



Ok, blah-blah. The second question here is about that curious "nothing meaningful" text. It's clear (to me, anyway) that the writer had a kind of "move along, nothing here to see" intent, but it just came out all wrong. Very, very wrong. And a point that I'm taking away from this is that that's what editors are for. I dug a bit into the history of this topic, and as near as I can determine, the odd text was dropped into the topic as part of a batch of last-minute fixes, and, again as near as I can tell, without an edit pass. Having been a writer for a very long time, I know quite well how this sort of thing comes about -- I done it my own self.

Looking at all of this from the safe perspective of very keen hindsight, we editors are convinced that nuh-uh, no way would we ever have let something like that get by us. No sir, not us. Easy to say, and -- whew -- the topic history gets off the hook in this particular case, seeing as how no editor apparently did look at it. I personally am using this example as a big ol' stick on my writers to, um, encourage them to send any change -- no matter how small -- past their editor.

API docs are unsexy topics to work on[1] -- they're repetitive, the style is, um, very economical, and by god, they're endless. (See Petzold, above.) But they're very important, as we know from users' comments and as we know ourselves as users. ("Read your own dogfood.") So we do have to do them right. Sometimes, however, we slip up. ("WTF?") In this case, fortunately, the slip-up, while vaguely embarrassing, isn't a showstopper. Even so, I think we'll fix this one for the next release.


[1] Some evidence for this is that open-source projects sometimes have sparse or erratic API docs.

[categories]   , ,

[3] |