I've realized that I know nothing about writing documentation. That is, I know nothing about writing documentation for anyone but myself. I guess I kind of knew this before, but it really came home to me a few weeks ago when I was trying to write up the things that are important to know about the tools I developed, things I've done that may need to be done again, and random knowledge that should not die with me. The essential need for that task is gone (I'm not leaving KCLS immediately), but the effort was not wasted. It was a good exercise, and now the documentation exists. Nevertheless, I fear that it is bad documentation.
I vaguely remember complaining to Meg about my lack of experience, and she mentioned that she had taken a Technical Communications class on documentation while she was at UW and that it was one of the most useful classes she's ever taken. Now I regret that it's too late for me to do the same, but I'm seriously considering signing up for the Computer Documentation
class in the UW Extension program in Technical Writing and Editing. The next one is not until next spring, but if I'm going to stay in IT, I need those skills. I've complained too much about shoddy documentation to accept less than the best from myself.
Joshua Daniel Franklin says:
Well nuts, you seem determined to post things I'm obligated to reply to. I've written documentation for my old job, the Cygwin project, and it's a decent part of my job now. I've not taken a "Technical Writing" class but since a lot of technical writing is crap that doesn't bother me. I've got a liberal arts degree, eh?
To me, there are a couple basic principles. I think I've picked these up from O'Reilly but I don't know for sure:
Use lots of examples (code if appropriate) and explain them
The standard tool for technical documentation is DocBook, but only use it if you need to. It's what O'Reilly, FreeBSD, Sun, HP, Red Hat, etc. use for their manuals. It's useful and powerful but takes some getting used to. If you want to learn it, check out the source to Getting Started with XML, the SelfDocBook (warning: it only works on Red Hat without tweaking the Makefile), and the Fedora Project Documentation Guide.
Laurabelle says:
Hmm. What you say makes sense, but I think my situation is significantly different from yours, at least at times. I guess there are two kinds of documentation that I have to produce. One kind is for people like me (specifically, Kathy and possibly The Next Intern), and the other is for Other People.
At this point I've written a bunch of custom scripts in the Dynix query language, which is called Recall, and linked them to one of the menus in Dynix so that staff who don't have access to manual Recall can run reports like lists of holdings and such. I tried to make the interface as intuitive as possible, but people still need help. So I wrote up some documentation, and the Web Services Librarian stuck it on the Intranet. I tried to be really thorough, but I really don't know what people know and what they need help with, and I have a feeling that it's not organized as well as it could be and therefore not very readable. I should take another look at it... and screenshots would probably be invaluable too. Good idea. (Kind of the equivalent of code in this case.)
I guess what I really need is tools for understanding what the audience for my documentation is going to need to know, when that audience works in another part of the system and has an almost completely different set of skills and knowledge.
Jim says:
"...you seem determined to post things I'm obligated to reply to."
Sigh! "Obligated", "orientated"... what ever happened to the simple words of my youth, "obliged" and "oriented"? And why are such changes so inconsistent... I mean, why not "determinated", too? :^(
Laurabelle says:
I'm with you on but and seem slightly different to me, not exactly in meaning but in context. It would have sounded strange if Josh had said he was
As for your other question, people are inconsistent, especially in very large masses. Therefore, language is inconsistent.
Jim says:
"As for your other question,...."
Hmm. I think I just got me a "rhetorical answer". 8^)