mike's web log

 

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

Paper's Law: It's not that simple.

Herb Paper, via John Lawler



 

Navigation






<April 2014>
SMTWTFS
303112345
6789101112
13141516171819
20212223242526
27282930123
45678910


 

25 Most-Visited Entries

 

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
 

Blogs I Read

 

Contact

Email me
 

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 4/3/2014

Totals
Posts - 2298
Comments - 2480
Hits - 1,618,814

Averages
Entries/day - 0.58
Comments/entry - 1.08
Hits/day - 410

Update every 30 minutes. Last: 5:05 AM Pacific

 
   |  No docs == no product

posted at 09:39 PM | | [1] |

I've been in this industry a long time, and may I note, long before the convenience of the Web and armies of bloggers and forum posters. So it's slightly surprising to see that a developer still needs to point this out to people. In his post "Why good JavaScript libraries fail," Nicholos Zakas lists as the number one reason ...
1. Lack of documentation. No matter how wonderful your library is and how intelligent its design, if you're the only one who understands it, it doesn't do any good. Documentation means not just autogenerated API references, but also annotated examples and in-depth tutorials. You need all three to make sure your library can be easily adopted.
But at least he's pointing it out. I am pretty skeptical of tools like GhostDoc, NDoc, and even our own Sandcastle. I have no issue with these as tools; AFAIK, they do just fine at their job, which is essentially to convert code comments into reference documentation. It's the job they do that bugs me. Or more precisely, the idea that running one of these tools produces -- presto! -- "documentation."

I'm hardly unbiased, since I edit (and write) for a living. But that's one of the reasons I am skeptical -- I read unedited text every day, and let me tell you, I see a lot of stuff that is not ready for prime time. Or more often than you might think, that doesn't even make much sense.

But Zakas puts his finger on a different reason that I am less than enthusiastic about these tools. Namely, that even a relatively well-written and comprehensive set of reference docs is not "the documentation." This is a popular point of discussion, even a kind of programmer machismo -- "Just give me the API docs and I'm good to go!" Yeah, well, maybe. If you already know what you're doing, API docs are where you'll spend all your time. But if you just walked up cold to a new technology, good luck trying to suss it all out from the descriptions of the classes and members. And that's if you're a smart guy, never mind a guy like me who is a bit slow on the uptake.

So yay for Zakas -- he's right on that a good doc set includes (good) examples and tutorials/walkthroughs.

To put this into context for us, one of the achievements of the ASP.NET team -- and I mean the team at large, not just the writers, but everyone up to and very much including Scott Guthrie -- is that there is a ton of documentation for ASP.NET and now for ASP.NET AJAX. There is of course the formal doc set, but take a little tour through the ASP.NET Web site (which I actually did for you -- #, #, #), and you will find scads, tons, piles, heaps of every kind of documentation you want. The value of providing extensive learning resources for the user base is extremely clear to the team.

We've been known to tell a developer "If it isn't documented, it doesn't exist." That's basically Zakas's point. Not only does it have to be doc'd, but it has to be explained and taught and demonstrated. Do that, and people will be excited -- not about your documentation, but about your product.

[categories] , ,