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?
Make it conversational as well as informative. You don't have to write a novel or make it into a drama play, but at least do something to help illustrate a bit more than some short and often mis-communicated list of what the options do. In technical speak? No problem: less man page, more info page (speaking of which, an actual info page would be a nice thing to have for a few of the projects out there, eh?)
Quo usque tandem abutere, Nimbus, patientia nostra?
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.
I was able to teach myself Pascal and C++ with the quality online Documentation in the Old DOS Borland Developer tools.
There are levels to the documentation.
Theoretical: Why is it here.
Actual: What does it do
Physical: working examples.
If something is so important that you feel the need to post it on the internet... It probably isn't that important.
Honestly I go back to UNIX books that were not actually intended for Linux specifically at all; those for System V worked great when it came to administering early Linux.
I've found later literature to not be as well written, and I've found many projects that aren't well documented at all, like the various GUI windowmanagers and login managers lately.
I suppose this bias toward old, good documentation is contributing to my dislike of Systemd, I don't see the same docs for Systemd that I saw for System V and BSD init structures.
Do not look into laser with remaining eye.
How can your theory explain that one of the best documented projects is developed by the most widely recognized assholes of the open source community?
are targeted to a specific audience. What is best depends on the audience. A manual aimed at a programmer may be written differently than one targeted at an end user, for example. While the basic content may be the same (examples, definitions, explanation of menus, etc.) how they are presented and in what detail may be very different. the main problem I see with manuals is they are often written by someone who may be a good programmer but has no idea who the audience is or what they need; which results in an end product that fails to meet the needs of the audience.
I'm a consultant - I convert gibberish into cash-flow.
The first hint that it's shit is that the Documentation link goes to a wiki. It gets progressively darker after that.
An important area to concentrate on is providing example usage. The more, the better.
10% of people want to write documentation without getting paid to
FTFY. Everyone on an OSS project wants the front-line job of coding (and are even willing to do it for free). No one wants to be the guy doing the hard, less cool but no less essential, job of writing the docs.
SJW's don't eliminate discrimination. They just expropriate it for themselves.
What I've learned from decades of reading professionally-written manuals can be summed up in two steps:
The first step in writing a good manual is to have a very weak grasp of the language used by your target audience. It is important to use many grammatical and spelling errors, just to make sure the reader stays on their toes and pays attention. Research has also shown that users do not like to read manuals that use advanced vocabulary or complex grammatical structures.
The second step is to manage the density of information on the pages properly. A piece of paper is pretty large, and so are most screens, so a lot of information can be included on a single pane of view. It is important to make the most of this space and convey as much information as possible, as densely as possible. The more information a user can see without having to turn pages, the better. Use of separating devices, indications, and other correlative marks should be avoided, as it takes away from space that can be used for more information. They also can cause there to be more whitespace on a page, which should be avoided at all costs.
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.
For everything else, there's MasterCard.
Get free satoshi (Bitcoin) and Dogecoins
I am already happy when the author has read http://www.xkcd.com/1343/ and some early manpages of sudoers (imho the worst, by far).
Todays "sudoers" manpage has already been cleaned up a lot and is still a horrible read. But in the past it was something like "the relevant configuration is a hierarchical list of geometrical weighted values. Each one represents a position in a list relative to its anchor". And yes, that was just a weird way of saying "/etc/sudoers contains configuration keywords with options".
Overall I had the impression the author was a sociopath showing off his mathematical skills while keeping the core knowledge unavailable to others.
"Life is short and in most cases it ends with death." Sir Sinclair
Based on the work I did in 1985 at Bell Labs as part of my assignment to create documentation requirements for the Acorn Network Control System -- Good documentation should have at least 4 parts. Each particular user persona would use the 4 parts in different ways. Part of the documentation would appeal to potential customers, novice users, intermediate users, users with limited but deep domain expertise, users who previously had fluency with the product but who lost that fluency due to lack of use.
#1 The first in additional to typical table of contents found in each manual there should be a documentation MAP, that combines all of the various documentation and training for a specific product into a visual map; typically this is done with a task orientation. Much like a web page site map, this will allow a potential readers with a wide range of user cases to find the right document or the correct chapter, section, and should include online training, videos, Etc.
#2 A quick reference guide which I think most users would be familiar with. This instruction is typically very linear, and walks at a high level users through the major steps for the most typical cases.
#3 A "cook book" best for coding applications but has broad application to most technologies. Each section of this manual details how to perform a particular task, in it's entirety; e.g., a recipe. Recipes should cover a range of users types (novice, intermediate, expert, or with specific previous domain expertise). A non-coding example would be: Recipe for setting up a mix minus recording using the Behringer Xenyx 1202fx mixer; the ingredients would include all cables, software, Etc. used in the recipe.
#4 A complete and full reference guide. Again typically found in manuals but often (today) the ONLY section of the manual. Each sub-section is a full and complete deep dive on each part, instruction, or option. This is typically used by experts. It can be used by those who are using the cookbook to look for recipe options and substitutions. It can also be used by potential customers to see if a particular use case is supported.
http://www.hawknest.com/
The Arch documentation is excellent.
Much of the Gentoo docs are really good, too.
If you spend all your time cobbling together enormous stacks from hugely bloated libraries with no maintainer,
So, in other words, the real world?
... it's important to remember what it's like to not know.
It little behooves the best of us to comment on the rest of us.
That should read:
Passive voice, should not be used.
John McAfee 'It was like that time I hired that Bangkok prostitute; to do my taxes, while I fucked my accountant'
And not because it has to be that way. The software is just poorly designed.
In an ideal world, user documentation would be written before the software so that an understandable, consistent, UI would exist. This sometimes happens, but even then, the implementation may not match the documentation (yes, I have seen this more than once).
Design principles like: simple things (and common tasks, even if not exactly simple) should be simple to do; the same technique should work in all contexts; etc. are often ignored in OS projects.
I have come to despair in trying to find a nice open source (Linux) object-drawing program that is intuitive (and thus easy to learn), has consistent behavior, and allows the quick creation of clean basic diagrams, and maybe has an additional level of finer controls for more precise work. The original Macintosh had this back in the 1980s with MacDraw, and the even more awesome MacDraw II. Complete novices could take the program and discover how to make good looking "boxologies" in minutes just by playing with the tools. Maybe such programs are still available on the Mac platform (I haven't had one in years), but no OS object drawing or 2D CAD program on Linux seems able to grasp what one of the first such pieces of software on the market was able to accomplish.
(Another really annoying thing to find in user documentation is self-praise about the product and accompanying documentation: making promises about how great the product is, and how wonderful the documentation you are looking at is, that are rarely kept.)
Starships were meant to fly, Hands up and touch the sky - Nicky Minaj
The problem with a lot of documentation is that they aren't written from a user's perspective - they are written by people who wrote the software, and know what to do. Letting go of your design assumptions is almost impossible.
I have long felt that the first draft of documentation must not be written by the person who wrote it; you have to allow your users to "send" you the first draft (either through email questions/screenshots/etc.). Then you realize how many assumptions you made that are non-obvious to your users.
Obviously, this isn't really practical for OSS - you might not be able to pay for usability testing and feedback. Which is why I prefer to include screen shots in documentation as much as possible. Also, I try to follow this basic formula for documentation: What (what is the user trying to do - make it clear what this section of the documentation address), How (how can the user achiever her goals), Why (this is where you might, if you choose, try to explain a design/implementation philosophy - it comes third, so that someone who doesn't care doesn't skip the entire section. Clarity and brevity are important.).
This is the principle I follow for user stories as well - create an end-to-end user workflow (which is basically just many small What/How/Why sections tied together).
One of my favorite sets of open source documentation are the perl man pages. They are written in an informal yet instructional style, and are *loaded* with useful, practical examples of how to use the language. Heck, I refer to "man perlretut" even when I'm not using perl, but I need a general reference for regular expressions. Sooooo useful!