Friday, 19 January 2007
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]
aspnet, writing, technology
|
link
|