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.
"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."
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?
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.
RTFA!
SJW's don't eliminate discrimination. They just expropriate it for themselves.
An important area to concentrate on is providing example usage. The more, the better.
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.
Agreed that the ffmpeg documentation sucks to high heaven. However, my nomination goes to OpenSSL. The existing documentation is scattered all over the place, incomplete, contradictory and misleading. Just like the OpenSSL code and API, it would seem that whoever is behind it made an effort to render it as useless as possible.
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 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.
is the Gnu Make manual. Better than the O'Reilly book.
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
F*** Summary is too poorly written to bother reading the F*** A******.
http://www.acetonestudio.com
The only technology that never needs a manual is the technology that no one ever uses.
SJW's don't eliminate discrimination. They just expropriate it for themselves.
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.
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.
As good a manual as I've seen for a Linux distro.
http://www.mepiscommunity.org/...
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.
Videos have their place, I grant. Especially when it comes to manipulating some object (could be a graphical object on a screen), where a verbal description just cannot compete.
But I hate "video documentation" with an undying passion. They have an extremely so rate of information transfer, typically very low information density (see how little text is in a 5 minute video script), cannot be scanned at all, require you to have an audible audio hook-up, cannot be copied for notes,... I'm just getting started here, but you get the picture. I can literally take in information 10 times faster in printed form, and locate relevant content even faster than that.
If video documentation is available as optional back-up, great! But if that is the only documentation, I will not use whatever-the-heck-it-is, I'll find something else.
Starships were meant to fly, Hands up and touch the sky - Nicky Minaj
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.
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
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
Read The Fine Manual
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.
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.
systemd is a seriously well documented project. At the moment there are around 202 man-pages.
http://www.freedesktop.org/sof...
Every man-page I have used is done by the book: good examples, relevant "See also" references, and sometimes even links to further information. I really like the fact that all config files have extensive man pages too (man journald.conf fx), and that they also provide "big picture" documentation like "man bootup".
I have often seen how a question on the systemd devel list resulted in clarification of the documentation, so they take their documentation seriously.
On top of the man pages, there is also a huge amount of information on the projects homepage, spanning from overview videos, to low level developer information.
http://www.freedesktop.org/wik...
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!
"RTFM" is defined in the first sentence of the first paragraph of the article.
Apache guy, Open Source enthusiast, runner
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!
Good documentation is typically not written by "most coders". It's written by writers. Some of us do indeed get a thrill from writing good documentation. I've been doing this for 20 years because it's fun, not because I'm paid for it, in much the same way that you have been coding, because it's fun. Different people find different things fun. The trick is to make it easier for these kinds of people to get access to the communities which are typically coder-dominated. (As you might guess, there's more about this in the article.)
Apache guy, Open Source enthusiast, runner
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!
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.
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.
Seconded. The documentation on systemd is outstanding, and a great example of how to correctly approach documentation for an open source project.
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.
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
Yeah, I even found a man page that list all the man pages : "man systemd.index" and a index for all unit directives "man systemd.directives" with cross-references to the relevant man pages. Really useful stuff that shows the developers cares about end users.
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.
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
I hate videos. Most are badly done, and take ages to get to the point or to the information I need. Sometimes they're good, but that's a rare exception and certainly not the rule. At least with bad documentation, I don't waste as much time.
Therefore, by the (faulty) logic you're using, you're just a cow with a keyboard - osu-neko (2604)
I forget who said it, but it's literally true that the only instinctive human interface is the nipple.
Everything else is learned.
When you have a kid you realise that this is not universally true. Some newborns have to be coached into using the nipple. Hell, they even have to be taught to sleep :-(
I'm a minority race. Save your vitriol for white people.
What's the best example you know of for open-source documentation?
Books from O'Reilly and Manning, I'm afraid...
My particular favorite was "DNS and BIND" (I think my first read through was with the 3rd edition). I read through cover to cover without my eyes glazing over even once. It was an enjoyable read, filled with interesting history and background that explained why various features were the way they were. It's a great read even if you have no interest in learning to use BIND, and it did a great job teaching me all about BIND and DNS.
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.
I call BS. I needed to do some stuff on ripe and instead of a text manual, they've given me a freakin 10 minutes video, great thanks for that.
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.