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

What the English depict with great talent is bizarre characters, because they have lots of those amongst them.

— Madame de Staël



Navigation





<May 2023>
SMTWTFS
30123456
78910111213
14151617181920
21222324252627
28293031123
45678910

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  
  RSS  
  RSS  
  RSS  
  RSS  

Contact Me

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 5/22/2023

Totals
Posts - 2647
Comments - 2657
Hits - 2,568,396

Averages
Entries/day - 0.36
Comments/entry - 1.00
Hits/day - 353

Updated every 30 minutes. Last: 4:02 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] |