Writing documentation, you know – it wears me out. Today I fleshed out something like 30 pages of documentation from 10 pages of notes. And you know the thing that worries me most? If I give this stuff to the average person in our shop, they’re not going to read it. 30 pages is just too damn steep.
The vast majority of it (26 pages or so) is focused on “how to do X…”. I’ve purposely made it very task based, but the size still makes me concerned. And really, I suspect what I need isn’t a paper document, but an online live-site internal document where folks can add their own “recipes” and notes on how my way of doing this or that is probably kinda dumb.
While I looking around the other night, I ran across another example of a nice live-documentation sort of setup – another example to stick in my set – Dojo’s manual. In this case, they’re hosting a book and a manual (one for a primer/introduction, one for a reference). Wiki’s have some great capabilities, but they almost seem a bit too flexible for the living document sort of thing. Organization is something you’ve GOT to impose on a wiki (if you want it, anyway) – and it’s easy to loose without constant vigilance. The jotspot wiki has done a nice job with it’s organization – very “book-ish” with every page having a “next”, “previous”, and “up” link. Okay – so very hypertext bookish anyway.
It does appear to have that minor little flaw of not showing images all that well… but that’s really the only downside that I’ve spotted there.
Where is this all leading? I’m getting darn tempted to see what I can create for a site that will do this live documentation thing – using Django, of course. I’m thinking that maybe I’ll set myself three two-hour blocks, and just see what I can whip up in that time. I’ve knocked out three other little app-template things at work (darned handy, that Django) – so I suspect I’m familiar enough to make a stab at this strange little personal sprint.
The downside is, we’ve already got a dozen places for storing documentation. Is another really going to do us any good? Ah, who knows. Maybe a worthy little challenge though.
Rhonabwy 