If It Isn’t Documented, It Doesn’t Exist

Posted on February 1, 2007. Filed under: Main |

 In my blogroll, I’ve found a few that I like, a few that I don’t, and a few that are just amazing.  is in the amazing category.

Why?  Because he writes what I need to know in a way that I can understand it.  I’m not a programmer, but I do write code when it’s necessary.  Does he look down on those who aren’t as good as he is?  Not that I can tell.  If he did, I’d quit reading (like I did Scoble).  Instead, he gives us tidbits like this one about documentation.

I’ll be honest, I’m not much of a writer, but I am a reader.  I used to work with a system that had 7″ worth of documentation stored in two volumes.  That’s whole lot of reading, but I had a few months on my hands so I did it.  Turned out to be the best investment of time for my career.  Because the developers and tech writers took the time to document every feature (what some would consider overkill) of the system, I was able to take that knowledge and apply it to five other critical systems that weren’t working right and fix them.

If they put as much effort into documentation for developers as they did for users, imagine the possibilities.  If you get that right, people will flock to your library/API, not because it’s better than the next guys (although that’s important, too) but because they can learn it easier and implement it faster.

Here’s the full post from Coding Horror:

Nicholas Zakas enumerates the number one reason why good JavaScript libraries fail:

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.

James Bennett expresses a similar sentiment in choosing a JavaScript library:

There’s one other thing which can really make or break a JavaScript library, and it’s surprising how often it’s overlooked, because the same thing makes or breaks an awful lot of software in other fields: documentation. The greatest library in the world would fail if the only way to learn it was reading the code (and, in fact, it already has to a large extent). Some packages have managed to overcome this by way of lots of unofficial documentation — blog entries and the like — but there is absolutely no substitute for full, well-written documentation. The ideal, for me, consists of:

  1. High-level overviews of each part of the library, touching on key objects and methods.
  2. Practical examples showing how to handle common use cases.
  3. Full API documentation for everything in the library. JSDoc is both good and bad for this: good because it makes API docs stupidly easy to generate, and bad because people assume that API docs are all you need. Javadoc, which inspired JSDoc, has wrought much ill on the Java world for largely the same reasons.
  4. Comments throughout the code itself.

Pretty much everybody who’s developing a JavaScript library has dropped the ball on this; very few libraries manage even one or two of those points, and out of the teeming multitude of JavaScript libraries floating around today I’ve seen exactly one which manages to hit all four points with any kind of success. Maybe there are other splendidly-documented libraries out there, but I’ve yet to see them; most treat documentation like an afterthought.

Mike Pope, who writes documentation for a living, neatly summarizes both opinions with this zinger:

We’ve been known to tell a developer “If it isn’t documented, it doesn’t exist.” Not only does it have to be doc’d, but it was to be explained and taught and demonstrated. Do that, and people will be excited — not about your documentation, but about your product.

Good documentation is hard to find. Particularly on open source projects. That’s why I was so pleasantly surprised to see such excellent documentation for the open-source UrlRewriting.net project, along with a support forum.

urlrewritingnet-documentation-cover

The UrlRewriting documentation (pdf) is a pleasure to read. Far from being an afterthought, documentation was a first-class citizen on this project, and it shows. The presence of good documentation makes the code a pleasure to use, too.

So how do you keep your documentation up to snuff on a rapidly moving project? Maybe it’s possible to use agile documentation methods alongside agile coding practices. Mike Pope’s recent post on the “agile little” ASP.NET AJAX documentation set is a hopeful sign that we, too, can generate better documentation, faster.

Source: If It Isn’t Documented, It Doesn’t Exist

Now that’s what I’m talking about.  Help me know how to help others and we’ll both stay in business.

Advertisements

Make a Comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

  • February 2007
    S M T W T F S
    « Dec   Apr »
     123
    45678910
    11121314151617
    18192021222324
    25262728  
  • Meta

  • Categories

  • delicious tags

  • Blog Stats

    • 10,504 visits

Liked it here?
Why not try sites on the blogroll...

%d bloggers like this: