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

Remember, loops are nothing more than a more pleasant way to write a "goto".

Eric Lippert



Navigation





<November 2014>
SMTWTFS
2627282930311
2345678
9101112131415
16171819202122
23242526272829
30123456

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 - 11/20/2014

Totals
Posts - 2315
Comments - 2504
Hits - 1,685,104

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

Updated every 30 minutes. Last: 8:28 PM Pacific


  09:39 PM

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]   , ,

[1] |