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?
What's the best example you know of for open-source documentation?
Books from O'Reilly and Manning, I'm afraid...
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.
"the more frequently a particular open source community tells you to RTFM, the worse the FM is likely to be?"
I've heard nothing but good things about the Arch Linux Wiki, and that's a community known for saying "read the wiki."
Maybe the author of the article needs to read How to Write an Article Worth Reading.
(Seriously though, his section on where is kind of interesting).
"First they came for the slanderers and i said nothing."
Hu?
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.
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?
Worked step by step examples.
Absolutely nothing left as an 'example for the reader'.
The trend nowadays is to sell you a separate book in place of the manual that should have come with the product in the first place....
The fine `man` has served me well over the years. At points, it is too terse or too verbose, but very rarely is it flat-out wrong.
As for other projects, that's what source code is for, right? No programmer worth their salt should be afraid to dive into a random piece of code to answer a question. It's an essential skill to go from having a question to finding the implementation details and understanding them. Often, this is the only way you get a concrete answer.
Yes, I write documentation for my stuff. Yes, I leave useful comments in my code. No, I don't expect there to be documentation for everything, and I rarely use poorly documented crap, but sometimes it is unavoidable. Most of the time, you just have to deal with it head-on (i.e., via reading source code). Occasionally, this includes fixing bugs in some poor sap's library, because you don't have the time to wait for them to fix it.
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.
When discussing documentation if thought about this rule:
90% of people want to have documentation
50% of people want to read documentation
10% of people want to write documentation
I think the above is the reason people don't write documentation. Few want to write documentation and they are often not motivated to write because people barely read documentation even if the see a need for it.
Knowledge is power. Knowledge shared is power lost.
The first hint that it's shit is that the Documentation link goes to a wiki. It gets progressively darker after that.
I'd like to nominate the FFmpeg libav* collection of libraries for the category Worst Documentation.
98% of the ffmpeg documentation is for the command line tool, the remaining 2% is an auto-generated Doxygen with barely any information.
It's so bad that you'll save time by looking at the source code of ffmpeg, the command line tool, instead of trying to look at the library's documentation.
An important area to concentrate on is providing example usage. The more, the better.
If you want good documentation, don't look any farther than Shorewall.
Don't forget to take your meds
Time for bed, said Zebedee - boing
Available here:
http://docs.shapeoko.com/
Some awkward aspects are imposed by the source being Markdown on Github, so lowest common denominator for special characters such as what should be em-dashes.
Interesting footnote to the project is that the note explaining how to use the interactive diagrams was deleted by a person who thought it was unnecessary --- less than half of the people who responded to a poll figured out the interactivity and almost all those who did find it were surprised by it.
Part of the reason it's hard to write good documentation is that it's hard to get people to make use of it --- similarly we've tried to get everything about this CNC router onto the wiki, but there are still an awful lot of forum posts which I answer w/:
``That's on the wiki:
Sphinx of black quartz, judge my vow.
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.
first off any good technology shouldnt need a manual
Secondly if you must have a manual get to the point and stop the mental masturbation.
This Linux Documentation Project was, for many years, stellar.
Quite detailed, and very well written, and was enough for a willing-to-learn newbie to download, read, and be able to administer their own unix-like Linux box. I think that was an unsung hero of Linux coming to be the dominant non-commercial *nix.
My perception recently has been that fragmentation of distros has left the LDP further behind. I bet starting from that and Slackware would still be a great way to learn Linux.
Bad FMs tend not to get read leading to more confusion and RTFM comments. WTFM!
Best example? Programming in Lua by Roberto Ierusalimschy. Great for Lua, and great for an intro to programming.
I do think the author is a bit mistaken though.Open source documentation sucks, in general, because writing documentation doesn't scratch the usual developer's itches. They want to code, not write.
The online help for Ubuntu was pretty good, got right to the point.
I haven't used Ubuntu in a long time (Unity) so it may have changed, but at the time was the best, and the easiest to use.
"If any question why we died, Tell them because our fathers lied."
So why is anyone surprised that no one seems to want to do a bunch of hard work that they don't really enjoy without getting paid to do it? Open Source can be fun to code so some people choose to work on it for free. Most coders do not get the same "thrill" from staying up late at night writing really good documentation.
Patience and empathy: "Take time out of your life to answer this question you've answered before and is easily found with a simple search."
Not patience and empathy, being a horrible person: "The answer is here [link]"
Get with the times, AC.
More seriously, there's a big difference between 'how do i do colision' and 'I read the tutorial on 2d physics but I can't quite understand it, here's my setup and what I'm not getting:'. One is helpful for both (those familiar enough to change the docs may discover information is missing or not well presented), and the other is disrespectful and lazy.
The best instructional book on a subject I have read was Cold Reading by Ian Rowland.
Nothing to do with anything "Tech" Technical; but just well laid out information that was really well structured and methodical.
I wish "Tech" Technical books were made that well. They tend to write unbelievably simplistic "hello world" books and then just jump to PHD impenetrable level written in "academic". Use the Dummies guide style and make make it PHD level info. i ain't book smarts.
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.
Voluntary software development is driven primarily by desire for self-actualization and recognition. People are willing to invest patience if this will allow them to demonstrate their superior skills and/or to get recognition for being skilled in the community.
But empathy - recognizing and providing for the needs of others and suppresing your own desire to prove yourself - does not come free. People need rewards and compensation in order to sustain it and therefore to combine "patience and emphaty". Programmers in jobs are paid in order to stop their inherent urge to create something "cool" and subordinate themselves to specs dictated by someone else and to yoke themselves together into a team assembled by someone else (code itself is made for free).
This is why OSS has a stigma of being "hard to use". Except if monetary or other rewards are provied, the programmers will empathise with themselves only and write software that is incidentally useful only for other programmers (Ubuntu and RHEL distributions, Firefox, LIbre/OpenOffice.org and many of other software projects are examples where significant part of the work was provided by paid contributions in order to get them to state useful for general computer-using population). Many other features which require combinations of "patience and emphaty" are weak in OSS, for example UX and graphical design, consistently removed bugs in code that requires manual testing (complex UIs), long term ABI and API stability, ...
And this is also the explanation for low priority of creating high-quality user-centric documentation in OSS projects.
(it's not me who figured this this out - it has been written by many people but I'm to lazy to google for the links now)
is the Gnu Make manual. Better than the O'Reilly book.
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
F*** Summary is too poorly written to bother reading the F*** A******.
http://www.acetonestudio.com
Just fuck you that's all, because your a fucking idiot anyone who doesn't coddle you and hold your hand is a bad person?
just fuck you again.
I knew any open source thread would eventually attract Richard Stallman.
Everyone knows the REAL money is in merchandising (and SUPPORT)
JMol is one of the worst. They have left pages and pages of completely obsolete versions lying all over the internet, and actually getting what you want from a search engine is near impossible. Once you do find the current JMol wiki, it is often incomplete, poorly written, and doesn't details common tasks that users want to accomplish.
Git's documentation is also bad. The problem with Git, is that it treats users as if they want to use Git as a programming language. Good git documentation would be organized around tasks a user wants to accomplish, so things like:
1. You just accidentally staged a file you don't want, here is what to do to back it out.
2. You forgot what you committed last time and stupidly, your commit message wasn't that revealing, here's how to list all the files that were changed.
etc.
Instead Git's documentation just gives you the arcane low level details of git, like
git fetch [] blahbalksdjgblkahblkash
Not even a little helpful, if you don't know what it is you are trying to do.
I think this is a common problem for programmers, is they are working in the details and can't see the bigger picture. No user cares about the details, they only want to know how to do what it is they need to do. And many of us don't have a week to spend learning the arcane niceties of some complicated (and feature complete system).
With git, I find that with one search on stack exchange I can generally find what I need, but searching the git documentation is essentially useless.
lack of cross-references. descriptions of exactly what, how and where. Module names, dependencies,
indexes, function lists, operational diagrams.
And the worst - writing documentation that assumes you know what the developer/programmer already knows... a common failing in most technical
people.... and for any newby ( to linux from windows, to apple from windows, etc... ) a failure of the documentation is a sentence to hard labor
for the amount of time to learn what the basics are, where they are, how it all works...
Learning a gestalt is what this is... not a planned learnig or complete description.
I could drop 25 books on you about mathematics and say " here's what you need to become a mathematician, just dig around..."
Or I could point you to newby books, online courses, and give a plan....
Something wlse I miss - pdf documentation so I can look at it when not online. I prefer to do it that way since being online is a hassle....
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/
Unless you want your readers' eyes to glaze over, write in active voice.
Title says.
As good a manual as I've seen for a Linux distro.
http://www.mepiscommunity.org/...
Excellent reference material, terrible terrible learning tools.
First page: what it does. Fine, but it doesn't define any of the terminology. http://www.mathworks.com/help/simulink/index.html
"Getting Started": Contains a product description and links to tutorials. http://www.mathworks.com/help/simulink/getting-started-with-simulink.html
click on the first tutorial (http://www.mathworks.com/help/simulink/gs/create-a-simple-model.html) and discover that they first introduce the Simulink Library Browser (a window with "blocks" in it) and then the Simulink Library Browser Toolbar (a set of icons in a completely different window that enables you to create "models"), without ever explaining what any of the elements are for, what their inputs and outputs represent, or what you're looking at. It's completely missing the big picture of what the heck you use it FOR.
See http://ctms.engin.umich.edu/CTMS/index.php?aux=Basics_Simulink for an example of the correct information, properly assembled and put together into something useful for someone just "getting started"...
Old GNU project manuals are VERY good. Bash and libc have incredibly detailed and clear manuals (in the form of info files, also available as pre-formatted PDF books). I think no one now writes documentation like that.
... 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.
and you can stop complaining about the free support you're receiving. I'm sure all the projects i work on will quickly find replacements who posses the customer service skills you expect, the ability to debug C code written by generations of people all of whom have different styles. AND do it for free
Let's be honest. Manuals are a concept best left in the 90s/early 2000s. With the advent of media sharing, communication platforms, like Youtube, or Skype, it would be far better to show a person what to do. No more looking through complex manuals trying to find "that one page". Textual interfaces are good for some things, but education has always been best at hands-on learning. Sitting someone down and step-by-step showing them how to do something in a video would be far more useful.
The best documentation I have dealt with start with an overview of the process you are going to go through, shows a non-trivial example, and only then going into the jargon filled nitty gritty references and details.
Way too much documentation only covers the detailed references with no clear context or useful examples. Folks in the know are prefectly happy, but folks at the bottom of the learning curve end up very frustrated.
Lots and lots of (simple) examples.
It's like the old adage in fiction writing: show, don't tell. (Although in manuals it helps to tell too.)
Some things are so blindingly obvious in hindsight that those familiar with the product apparently can't imagine why you'd need to show an example when the abstract explanation of the API or UI is so straightforward. Well, it may not be so straightforward to somebody who has never used the product, and your abstract explanation may be full of ambiguities you don't realize are there because, obviously, there's only one correct interpretation.
I write this having just spent the better part of a day trying to figure out the particulars of a REST call when all that was in the doc was an example of the CLI command and the name of the REST endpoint (carelessly omitting the rest of the fricking path and what keys were expected in the JSON for POST data). A one-line curl example would have saved me hours. Of course now it's obvious.
Well, simple: documentation does not fall from the sky.
It has to be written; when people commit to the objective, things actually do happen right (and if you have no time, it is always possible to delegate).
AutoIT has the best manual. NeHe OpenGL tutorials are the best tutorials. Outside of those two, most everything is suck.
I always think of the man pages on the Linux command prompt when thinking of the worst documents out there.
I really think whoever writes into these has no idea how to make them human readable.
I couldn't be bothered most of the time and ended up googling for what I needed to do instead.
Open source code faces a special obstacle when it comes to quality documentation. By the very nature of the ecosystem, open source projects derive from the needs of those who are directly contributing to it; the experts, in fact, and thus any artifacts the project produces will be based on their requirements, not those of casual users. It's not only required, but expected that in most cases, a user will be knee deep in the lower level details and have a high level of proficiency and knowledge of not only the system, but contingent details.
In fact, I can remember a time when creating a user-friendly webpage for open source projects - one with bubbly callouts, animated page features, and tutorial videos - was seen as some sort of sell out - proof of corporate sponsorship or the like. We know that providing more than just a link to the source code and a paragraph or two is a significant effort, much less organizing all the information in an immediately useful way is a huge time and effort sink. That's time and effort that could have gone into bug fixes or feature enhancements. For the intended users, it's sort of a waste.
Yeah, chicken and the egg situation here, good docs = more users, more users = more need for good docs, but that's only the case if 'large number of users' is a higher priority than bug fixes or feature enhancements (and it very well may be!).
So it'd be nice to have better documentation, and not just hope that stack overflow will be there with a solution, but like the example citing non-english speakers - is that part of the scope of the documentation? Is that the primary target? Is it worth our actual time? And if so;
- How do we motivate people to write good documentation?
- How do we attract quality technical writers?
- How do we know when we've written good documentation/what are the criteria?
- How do we know how to limit our documentation? How much is enough, and how much is too little?
- How can we place an explicit value on that documentation, vs. other concerns like bugs and feature development?
The article pointed out some good arguments for better documentation, but barely touched on the bigger problem - how do we get people to actually write it, and how do we write it once we've decided to.
I remember when first getting into Linux, I had a HORRIBLE time figuring out what 'ln' (link) did, cause all the docs skipped around defining it.
I wrote up some real world docs way back then and they turned into one of the most popular posts of all time on my site:
Symbolic Links: Defined
Hands down excellent. High-level overviews, more detailed usage guides, fully-detailed references, and internals. Well-written, well-organized. And guess what else? A TABLE OF CONTENTS at the root, so as soon as you find your way to the docs, you can see what's there and how they're organized. Too many OSS projects lack that. (Oh sure, there's tables of contents, lots of them, for individual areas of documentation which are spread all over the place--not the same thing.)
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
If we had an Index File, we could look up the Index File in the Index File!
Gary Cutler's GNU COBOL Manual is superb.
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).
Which I had published in the now-defunct SysAdmin magazine in '06. http : //24.5-cent.us/egoless_docu.html
mark
For a comprehensive look at what can be done with a very unusual language, the J essays are hard to beat: http://www.jsoftware.com/jwiki... . They provide context around why you might want to do something one way rather than another and are much more literary and wide-ranging than typical documentation.
The details of the vocabulary - linked to from the "Vocabulary" page (http://www.jsoftware.com/jwiki/Vocabulary) are also pretty good because they combine general definitions with explicit usage examples.
So here's the gist : I am all in favor of rtfm.
However there is a rather big misconception of the relationship between the quality of your documentation, and your legitimacy when you saying to someone : "rtfm!", especially in the open source community.
If your documentation is less than 80% accurate / up to date, I'm moving to say you have no ground to stand on.
You cannot ask someone to spend time reading and learning stuff about your product/project, when 20% of what is going to learn is outdated crap that is at best useless, and at worst very harmful.
And that's true even if the question he is asking is very well covered in the doc. Because if you doc is to outdated, people will know and they won't be encouraged to read it.
I think there is a lesson to learn looking at what makes successful (open-source) projects successful. If you look at Golang or Docker or React.js, their documentation and learning material are awesome. Because of this people are confident that they can invest time learning by themselves, from the documentation, and that it will be worthwhile.
There's an XKCD comic for everything.
You can be a programmer and write documentation, but if you want good documentation, the person writing it shouldn't be the same person who wrote the code.
The problem is that you're already too far in -- you understand the design issues, the quirks, etc. You need someone with a fresh view to write the documentation who doesn't come in with a lot of implicit knowledge of the inner workings of the software.
My boss has a policy that it's the newest or youngest person on the project's job to write the documentation, for that very reason. (the others still review it, but they write the first draft).
Build it, and they will come^Hplain.
First, whatever became of of the FM which used to come with the software? Billy Gates and Co. halted it, so their Micro$oft Publishing Co. could reap profits from forced purchases by the noobies.
The very best documentation I've ever read --- and I suspect was written by engineers --- was the Perkins-Elmer OS 8/32 Processor Manual --- once this was read through and through (took me about 50 times) one completely grasped and understood the operating system at the hardware level/software level --- truly a beauteous proposition!
The next wonderful documentation was provided by Mark Minasi, on the private or commercial side, but I don't believe he is writing it anymore, but his books were top notch!
People to be avoided were technically ignorant types like Scott Mueller, who was simply a copyist, and would copy long lists of hardware parts (a great list compiler) but simply and obviously didn't understand hardware or computer sci.
But my experience --- and many others --- was that once outstanding inhouse documentation is written, the efftard bosses usually believe they can do without you!
In other words, if you are going to contribute to open source software, then WTFM.
Best: gentoo handbook (at least from like 10 years ago)
Worst: too much bad documentation out there to pick just one
Most linux users don't know this, but the man pages were named after Chuck Norris. Chuck Norris fsck'ing hates noobs!
As a professional tech writer, I can say without reservation that programmers should not be permitted to write documentation.
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!
Here is a new idea let just use common sense. like write the manual based on the fact that the reader has never used your application or product before. And don't leave anything out document all the feature and options.
Just saying!
It's possible for a programmer to write good documentation, but only if:
1. They're writing it for other programmers, preferably ones already familiar with the product.
2. They're able to think like a non-programmer.
#2 is very rare, IME.
Slow down, cowboy! It has been 4 hours since you last posted. You must wait another few hours.
What's the best example you know of for open-source documentation?
It's not open-source documentation, but the same general principles ought to apply. Years ago I bought an Epson dot matrix printer. The first chapter was called "Quick Start." Quick Start told you how to get up and running with the minimum of fuss. For example, it said, "connect all the cables" instead of saying, "connect plug a (pictured) of cable monster (pictured) to jack b (pictured) of printer 345DEF (pictured), along with all the warnings about what damages and injuries might be caused by improper connections of cables. The manual's author assumed the buyer was fairly knowledgeable and simply wanted to print his first file as quickly as possible. So, with a task at hand, and a knowledgeable user, the chapter because a quick, two page, guide that served as either an introduction or a reminder of how things work.
Chapter 2 did the same as chapter 1, but this time with all of the details. People used it to set their printer up using chapter 1, then, if they had trouble, would go to the corresponding portion of chapter 2.
Chapter 3 introduced seldom-used features by describing a task that required that feature and then describing all of the steps necessary to use that feature. It was only with chapter 4 or subsequent chapters that every detail of every possibility was described.
In short, the manual was task-oriented, tasks being the things the user wanted to accomplish, rather then being function-oriented, functions being the things that various parts of the printer were capable of. Engineers and programmers tend to be function-oriented because they design the various functions. Users tend to be task-oriented because things are tools used to get other things done.
I wrote a manual based on the organization of the Epson manual years later. I heard one story of an operator holding up my manual, and telling the speakers, "that's the way to write a manual." It's one of my proudest accomplishments.
~Loyal
I aim to misbehave.
Maybe related to this topic, there was an article about how more and more companies are not providing useful customer support because they figure users will present, discuss, and solve problems in forums. Which I have found not many forums are useful except only reading about others have same problems as I do. i.e. video-to-usb adapters which seem excruitatingly difficult to use (easy to connect but always a crapshoot if video signal is recognized). Another gripe I have on forums are several group categories and if you don't post your question in the proper forum and with narrowly defined topic (each has specific topics of hard defined terms, none with specific topic of your question), the ban hammer will come down quick and you will be banned for life. But then many products are cheap Chinese made so get one off buy-it-now on ebay and if it doesn't work, send it to the trash to contribute to landfill ewaste problems.
mfwright@batnet.com
As I was learning to program in python I used codeskulptor during a course I was doing. The docs supplied for python and a few of their own packages were a god send after wrangling with pythong docs. What I like about it is the clear example code provided. It's not long winded. It's straight to the point. Very clear concise. But there's little room for wondering from the example code they provide. I'm better with Python official docs now, but when I was starting it was so damn hard.
It is absolutely spot-on correct.
As someone who has written a fairly extensive FOSS project, along with all the docs, I constantly encounter people asking me questions that are explained in the docs.
That means that I failed; not them.
I'm learning -slowly.
Most programmers are not writers and will never write truly great documentation, but something they or someone at their level of familiarity can get. Most OSS is written by programmers who actually have a day job doing non OSS work. In closed source world (unless your product ofcourse is an api), documentation is often sacrificed in the name of "time to market". Those habits carry over to the open source projects too.
Unless there are more volunteers who want to write documentation for OSS, good documentation will not be written.
I enjoy reading most of the documentation associated with OSS. Not only is it informative, but there is usually a little technical humour thrown in as well.
The worst documentation, imho, are usually the instructions that come with products that have "some assembly required". Sometimes there are no English instructions; or very, very poor chinese-to-english translations or pictures that don't make sense or are inaccurate or erroneous in some way.
On the bright side, it's extra practice for problem solving skills.
Political correctness is really just herd psychology pushed by insecure people who desperately seek social conformity.
As a technical writer the best and fastest system I have seen for writing manuals is called "Information Mapping". It is a system for structuring technical content so that a user can quickly navigate to the thing they need without having to read the whole manual first. It is designed to cope with the limits of human working memory, and get tasks completely quickly and accurately.
http://en.wikipedia.org/wiki/I...
Here is the commercial site (I didn't go here, but had some training from other local Information Mappers): http://www.informationmapping....
If you are a software developer you can learn the concepts in about half-a-day, and your manuals will be awesome as a result.
Just RTFM
Trestle is the UI system that comes with Modula 3. Its programmers' manual is *excellent*. And, furthermore, it was machine-generated from the source code, which made it easy to keep the manual up-to-date as the code evolved.
And, yes, it still manages to be excellent.
There was a lot of thought put into it. There was a lot of thought put into writing the comments in the code so that they would yield comprehensible documentation, including a gradual (though quite technical) introduction to the subject matter.
Generating documentation from source code doesn't have to produce garbage, though it will if the programmer pays insufficient attention to the issue. And paying attention to the generated documentation during coding pays off in clean interface design, because a clean design makes documentation easier.
-- hendrik
Someone said that : If you cannot explain something with simple words,then you might have not yet understood it correctly...
This reminds me of one ot the things that I admire of Hollywood movies.
They might be addressing very complex human problems. But they show it in such a simple way. Perhaps with an image, that everybody can understand it.
Movies are what humanity was missing after discovering books and their way of inheriting knowledge.
Because, when we, for example, read about an insurrection in a history book. We might just highlight the most interesting parts, and be sure that we know about the subject.
But for those people that lived it, it could have meant much more: years of slavery, the joy of meeting others that shared the same idea, and the moment when everybody envisioned a change and did something about it.
That all is what we actually ignore when reading a book.
Perhaps, because writing about that does not matter in our days.
Or perhaps, simply, because emotions are not easy to transmit when you write a book.
But the audiovisual experience that Hollywood invented, might help a lot in future learning.
PostgreSQL - http://www.postgresql.org/. They also have the best/most friendly/most helpful IRC channel I've ever visited.
The problem with JavaDoc dumps and similar API documentation is that it has what something does, but not how to do it. What manuals need is the how part - show us with examples what to do in what order to get the results we want.
The pet peeve that I run into most with manuals, esp. motherboard and hardware manuals, is that it was written in one language and then translated into several others. This seems to lead to function descriptions and explanations that make no sense in the translated languages. Or my personal favorite is, 'Feature Name: {Options: On|Off}, This turns toggles feature name on or off,' with no explanation of what feature name is and why/when it should be turned on or off.
A manual should contain useful explanations and descriptions of a device or program's feature set, and be readable/logical in whatever language you are reading it in. Anything else is a failure.
"why's (poignant) guide to Ruby" is still the best manual for a programming language that I have ever read.
as the needle in the haystack
a) Other languages have the same idiom
b) It's understandable, even if its no idiom of a particular language.
Hire Dru Lavigne.
After a photograph of two typewritten pages with editor's marks all over them, which he says is a fourth or fifth draft: "Writing is hard work. A clear sentence is no accident. Very few sentences come out right the first time, or even the third time. . . . If you find that writing is hard, it's because it is hard." --- William Zinnser, On Writing Well However, the first fifty pages of that book, along with The Elements of Style have helped me write much better must faster.
After a copy of two typewritten pages with editor's marks all over them, which he says is a fourth or fifth draft:
"Writing is hard work. A clear sentence is no accident. Very few sentences come out right the first time, or even the third time. . . . If you find that writing is hard, it's because it is hard." --- William Zinnser, On Writing Well
However, the first fifty pages of that book, along with The Elements of Style, have helped me write much better.
Blender: http://www.blender.org/manual/
The worst are pretty much anything requiring me to type "man" in a terminal.
Buy your next Linux PC at eightvirtues.com
If application expectation is going the way of what has been in the App space for some time, perhaps documentation should not be necessary.
The presence of extensive documentation simply shows that the use cases are not obvious or clear to execute.
Documentation presently, is simply filling the UX gaps and counter-intuitive pathways that have been baked in to the application.
The best documentation is the doco that is so obvious to all tested users, that it is not required.
The linked photo of multiple locks on a gate was funny. But that does happen in the real world: multiple gates on a property, multiple key holders, but not every key holder is supposed to have access to every gate so they put multiple locks on some/all gates to enforce that. And yes, there are locks now with digital keys to address that very issue but, as someone pointed out on /. recently, they're not overly secure as far as locks go.
Keep
It
Simple
Stupid
also
Pictures
Enumerate/Examples
Numbered
Illustrate importance
Share stories
Ever used enterprise software? Horrible horrible documentation most of the time, perhaps done on purpose to 'promote' their training courses.
User software (for the user friendly windows & mac), most of the time you have to figure it out yourself.
And the list goes on and on... ofcourse there are examples of good documentation in any type of software too. The point i'm trying to make is that the documentation quality problem affects all types of software.
On a long enough timeline, the survival rate for everyone drops to zero.
The problem with technical writing for OSS is that you have to be able to understand the software before you can write the documentation. Especially when the existing documentation is bad and wrong, the battle is an uphill one. Oftentimes the software doesn't even build when you follow the official build process, and the one or two developers who have a working toolchain don't actually know how they got there and can't tell you. They can only tell you which packages are in their toolchain now.
Authors need to take a certain amount of responsibility for the documentation for their software, and at least give enough information for someone to get into it and do things, if they want someone to come along and write documentation for free.
"You're right," Fisheye says. "I should have set it on 'whip' or 'chop.'"
Get a copy of this book: Style: Lessons in Clarity and Grace by Joseph M. Williams (Author), Joseph Bizup (Author). Read it and obey it.
It teaches the reader how to write and rewrite based on what cognitive science has discovered about reading comprehension and motivation.
Some of the important basics are - avoiding the passive voice (with WHY you should do so and a very compelling discussion about AGENCY); chaining ideas from one sentence to the next and one paragraph to the next so cause and effect tracks with attention; how to group information so the reader remembers it; how to reinforce an idea.... Every page is a revelation.
From my own experience, I find reasons connected to examples go VERY far. Using examples, even for very complex things, was something to which Richard Feynman credited much of his success. He believed that if you couldn't come up with an example that illustrated the problem then you didn't understand the problem.
Also, PLEASE lead with the one or two things you know someone needs. Handle the 80% who are there to set something up and leave. A good anti-pattern for this is the man page for ifconfig. As man pages go it's very good but it requires digging to construct the line in the shell one might need. People go to the man page for ifconfig to connect to a wired or wireless network and have the most challenges with wireless. The top of that page (and many other man pages) should read something like this: If you are connecting to a wired network, get THIS + EXAMPLE information by doing THIS + EXAMPLE and then use it to do THIS + EXAMPLE. If you are connecting to a wireless network, get THIS + EXAMPLE information by doing THIS + EXAMPLE and then use it to do THIS + EXAMPLE. After each THIS + EXAMPLE have a statement like, "you'll probably see something like THIS" with an explanation of how to use it. Then it should have a basic, advance and troubleshooting section followed at the end by a related concepts section that you can use to find other man pages that might be helpful.
Every rule has more than one consequence.
Argh OpenLDAP. The docs are not quite there, and the boards are dismissive, if not outright hostile, to users who want a straight answer to simple questions. Anyone who gives you a RTFM regarding a massive tome like the OpenLDAP guide is an ass. I'm talking to you, Howard. (By the way I did RTFM, and found dozens of out-of-date instructions.)
Steve O.
I am really, really exhausted.
The problem is that people don't understand the types of documentation that they need. More people should read this article: (yes, I wrote it)
The 8 Types of Technical Documentation and Why Each Is Important
http://www.rhyous.com/2011/07/...
Best doc is for Apache web server...worst docs are for OpenOffice. That said, tech writing is an art form and writing good manuals takes a lot of work and a lot of time spent with developers and designers. In true FOSS fashion most of the developers get really rude and abusive when questions come up from the tech writing folks. I attempted to contribute that way because I am a lousy programmer, but a decent tech writer. The hatred towards the tech writers from the developers was just too much and I quit. Here someone wants to spend their spare time to contribute and all I got was personal attacks and no answers. So no wonder that the FM is really a FM because those who put the FM together are people who either like to be mistreated or are the developers who give a F about documenting anything that doesn't boost their ego. No idea why Apache web server is so well documented, even the config file is extremely well documented so that one barely needs any other documentation.