Obessed with Documentation?

| | Comments (0)

Those of you who have been working with me a while (say a month or more), know that I care very deeply about documentation...maybe to the point of a (minor) obsession. But how and why did this happen? Do I derive any benefits from this? Does the community? Let's discuss:

My Testing Notes

A lot of documentation happens because I am attempting to explaining something in a way that is comprehensible to me. For instance, when I first began exploring the wonders of Unicode and Accessibility, I encountered a lot of information which told me what to do but not HOW to do it.

For instance, in accessibility, a common recommendation for rollovers is "Use stylesheets". OK, but ... could you be be more specific? Is there code out there I can borrow? Back in 2001, it was hard to find good resources, so yes I tested (a lot) and I have shared (see http://webstandards.psu.edu/accessibility/tech/rollovers).

Now if I can get stuck, I can copy and paste the code I need. This is one reason why there is so much parallel documentation out there - the "official" documentation isn't providing enough detail (or the right kind of detail).

If You Mandate...Please Provide a Path

This leads me to my next point is that I believe that if I make a recommendation, that I am obligated to point you somewhere which tells you how to accomplish this (even if the recommendation is to hire a programmer).

For instance, if I recommend using Electronic Reserves in ANGEL, I know I can point users to either http://angelkb.ais.psu.edu/article.asp?article=1325&p=2 or http://www.libraries.psu.edu/psul/reserves/angel.html for the how-to. Because, if I don't, who knows if the instructor will take the time to figure it out?

Unlike a video game or cruising iTunes, I'm convinced instructional tools are generally considered work tools for many instructors and not something you want to spend time "exploring." Hence I do tend to structure docs in small just-in-time pieces which are optimized for searching (if not browsing).

Build it and They Will Come

I've been involved with "growing" a number of communities, but honestly the most "action" I get from the outside world is (ahem) the Unicode information. A lot of times it's to correct a typo, but sometimes it's a request for more information (the answer of which may get incorporated into the site) or just new information. It is more collaborative than it first appears.

On a slightly higher level, building decent, comprehensible instruction does lend your site an air of trustworthiness. If you can write material people can understand, you probably know what you're talking about. As a result, I do get some interesting referrals from time to time.

Room for Improvement?

Of course there's always room for improvement. For instance I always struggle with how to connect the pieces I have scattered about. I had one person looking at the Spanish accent code page ask if I could develop one for French. Clearly the navigation wasn't working for that person...

Another struggle is to satisfy all audience needs. Some people need all the details, but others find it overwhelming. Some people need video, and others get by on reading with images. I know I skew in one direction, but is it always the right direction?

And finally, I have to confess the other reason I love documentation - I'm good at generating it. I say with this with the humility of someone whose ITS Training attendees give so-so marks for presentation but very high marks for the written documentation.

It's at times at these, that I am grateful I can point confused students to quality documentation!

Leave a comment