Slashdot Mirror
RTFM? How To Write a Manual Worth Reading
An anonymous reader writes with a link to Rich Bowen's insightful, detail laden piece at Opensource.com about improving documentation: Have you noticed that the more frequently a particular open source community tells you to RTFM, the worse the FM is likely to be? I've been contemplating this for years, and have concluded that this is because patience and empathy are the basis of good documentation, much as they are the basis for being a decent person. What's the best example you know of for open-source documentation? How about the worst?
Coders they got. Projects whose "documentation" consists of anything more than a technical list of bugfixes they don't.
OSS needs to realize that well-written documentation is just as important as well-written code.
SJW's don't eliminate discrimination. They just expropriate it for themselves.
Make it conversational as well as informative.
On a related note, often with OSS there are more than two parties in the conversation.
If I'm configuring some sort of local mail store, I don't just need to know how to set up Dovecot. I need to know how to set up Dovecot, Postfix, Roundcube, and so on, and I need to know how to set them up together.
If I'm configuring some sort of Linux server, I don't just need to know how to set up RAID, I need to know how to do it with logical volumes for future-proofing, and I need to install a bootloader that understands. And then I need status monitoring, and procedures for recovering after failure, adding more capacity, and so on.
Frequently with OSS, particularly sysadmin-type stuff, I find there is more detail than you would likely ever need about any one part of the system, but the real problem is figuring out how to connect it all up in practice.
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.
Strongly disagree, documentation should get straight to the point.
Detailed reference documentation, yes.
But more often than not, the problem with OSS seems to be that no-one wrote the introduction/overview/big picture stuff, and the developers instead expected that users would just magically discover that kind of understanding from 1,943 man pages with cryptic names and no context or navigation to show them where to start.
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.
So years ago I was in varying positions at an ISP, but regardless of title "head tech" pretty much applied. We kept getting kids right out of high school that claimed to know computers well but had never used a command line, didn't know what an IRQ was etc.. As this was the Windows 95/98 era and this was a dial-up ISP some manuals had to be written.
I of course wrote them.
I made flow charts for email troubleshooting (I hated Visio so I used a graphical editor instead), I had grids for IRQ/Address settings, I had step by steps for undoing AOL I.P. stack sabotage (how many of you remember that?) Fact was I wrote really good documentation that anyone from teenager to adult could use to troubleshoot the "normal" day to day issues a worker at an ISP faces without making a condescending script. If you used it for reference it was an answer key, if you read every word you often would know why that problem occurred. I'm of the belief understanding an issue is always better than just knowing what the fix is.
Long story short - the documents leaked out of the company. On the north side of town there was a help-desk outsourcing company that tended to have a lot of employee migration with our own - in both directions. A buddy of mine went to work at a different ISP and saw my documents turn up there with my name replaced on the credit line (he knew I wrote them - he watched and knew the marks I put in things that were dead giveaways it was my stuff).
I no longer worked at the old company and was still finding out about my documents leaking all over the damned place. I decided to put the documentation GPL on the things and throw them out on my webserver. If figured if I put them out on the web myself then there was a verifiable copy out in the wild, it would shine a light on the plagiarizers, and I was hoping to maybe get offered jobs or something. Later I was criticized with "that really should have been Creative Commons". Fuck you, I did this before Creative Commons even existed.
My web server and the backups were physically stolen from my home, but there's still an archive. To this day I still write in the "explain it, don't step it" method.
Turns out lots of places want idiot guides and don't care to understand.
The preceding post was not a Slashvertisement.
I totally agree.
I've seen countless man pages that don't even bother to say what the command *does*, let alone *why* you would want to do that. They assume it is all self evident (I'm guessing the author's logic was: "or else why would you be reading about the flags if you didn't already know you needed it and for what?").
Also, sometimes explanations are vague--being precise about the behavior (especially if it is altering data) is important.