Comments on: Documentation is like… http://blog.niceperson.org/2004/05/04/documentation-is-like/ Making it up as I go along. Mon, 30 Aug 2010 10:16:09 +0000 hourly 1 http://wordpress.org/?v=3.0 By: Joshua Daniel Franklin http://blog.niceperson.org/2004/05/04/documentation-is-like/comment-page-1/#comment-304 Joshua Daniel Franklin Wed, 30 Nov -0001 00:00:00 +0000 http://blog.niceperson.org/2004/05/04/documentation-is-like/#comment-304 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: <ul> <li>You are writing for yourself (well, for someone with similar skills and experience)</li> <li>Keep it simple but without talking down. If someone just needs to spend some time with <cite>Learning Perl</cite>, tell them, don't try to restate the whole book in your own words.</li> <li><p>Use lots of examples (code if appropriate) and explain them</p> <p>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 <a href="http://www.infomotions.com/musings/getting-started/">Getting Started with XML</a>, the <a href="http://cyberelk.net/tim/docbook/">SelfDocBook</a> (warning: it only works on Red Hat without tweaking the Makefile), and the <a href="http://fedora.redhat.com/participate/documentation-guide/">Fedora Project Documentation Guide</a>.</p></li></ul> 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:

  • You are writing for yourself (well, for someone with similar skills and experience)
  • Keep it simple but without talking down. If someone just needs to spend some time with Learning Perl, tell them, don't try to restate the whole book in your own words.

  • 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.

]]> By: Laurabelle http://blog.niceperson.org/2004/05/04/documentation-is-like/comment-page-1/#comment-305 Laurabelle Wed, 30 Nov -0001 00:00:00 +0000 http://blog.niceperson.org/2004/05/04/documentation-is-like/#comment-305 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. 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.

]]> By: Jim http://blog.niceperson.org/2004/05/04/documentation-is-like/comment-page-1/#comment-306 Jim Wed, 30 Nov -0001 00:00:00 +0000 http://blog.niceperson.org/2004/05/04/documentation-is-like/#comment-306 "...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? :^( "...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? :^(

]]> By: Laurabelle http://blog.niceperson.org/2004/05/04/documentation-is-like/comment-page-1/#comment-307 Laurabelle Wed, 30 Nov -0001 00:00:00 +0000 http://blog.niceperson.org/2004/05/04/documentation-is-like/#comment-307 I'm with you on <q>orientate,</q> but <q>obliged</q> and <q>obligated</q> seem slightly different to me, not exactly in meaning but in context. It would have sounded strange if Josh had said he was <q>obliged.</q> As for your other question, people are inconsistent, especially in very large masses. Therefore, language is inconsistent. I'm with you on orientate, but obliged and obligated seem slightly different to me, not exactly in meaning but in context. It would have sounded strange if Josh had said he was obliged.

As for your other question, people are inconsistent, especially in very large masses. Therefore, language is inconsistent.

]]> By: Jim http://blog.niceperson.org/2004/05/04/documentation-is-like/comment-page-1/#comment-308 Jim Wed, 30 Nov -0001 00:00:00 +0000 http://blog.niceperson.org/2004/05/04/documentation-is-like/#comment-308 "As for your other question,...." Hmm. I think I just got me a "rhetorical answer". 8^) "As for your other question,...."

Hmm. I think I just got me a "rhetorical answer". 8^)

]]>