About

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

Read more ...

Blog Search


(Supports AND)

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

Quote

Writing manuals is a very special and privileged task in a computer company, for in the process of writing them you are forced to go over every detail of the hardware and software the company sells in an attempt to make it understandable and usable in our extremely broad customer base. In the process a conscientious writer will discover nearly every good and bad feature of the system, and can provide valuable feedback to the designers and implementers.

Jef Raskin



Navigation





<December 2024>
SMTWTFS
24252627282930
1234567
891011121314
15161718192021
22232425262728
2930311234

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 - 9/4/2024

Totals
Posts - 2655
Comments - 2677
Hits - 2,716,085

Averages
Entries/day - 0.34
Comments/entry - 1.01
Hits/day - 347

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