It's the Documentation, Stupid! 105
Roblimo writes "Brian Jones, a sysadmin for Princeton University, has written a Linux.com column that says open source developers need to provide better documentation if they expect support from sysadmins like him: 'With documentation, I can get to know the software,' he writes. 'Then I'll install it on a test box. If it works, great, I'm tickled pink. If it doesn't quite work, then I'm interested in giving feedback, because here's someone who will roll it back into the product or the documentation. This is a useful cycle that benefits millions, not the least of which is the coder! Documentation ends up resulting in a more mature product! Wake up!'"
In other news... (Score:3, Insightful)
Re:In other news... (Score:3, Funny)
I wish there were some way to lock this article so yours would be the only comment.
Bob-
Re:In other news... (Score:3, Interesting)
On the other hand, closed developers are forced to make documentation by their superiors. Just becasue you don't find all those windows are make help files
Re:In other news... (Score:1)
Who needs documentation when you've got the source code? Documentation is hard to keep up to date, and hard to translate. Sysadmins who are scared of the source, scare me.
Re:In other news... (Score:2)
People who actually have jobs, work and are busy.
Documentation is hard to keep up to date, and hard to translate. Sysadmins who are scared of the source, scare me.
"Being scared of the source" and "not having the time to decipher thousands of lines of poorly written and often uncommented C" are worlds apart.
Re:In other news... (Score:1)
Not at all. If you can't grok the source, either the program is badly written (just like documentation can be badly written), and you should look for something else, or you have no business being a sysadmin.
Re:In other news... (Score:3, Insightful)
If you can setup, say, Samba - using only the source for documentation - in the same time someone else can set it up using the real documentation, you have my deepest admiration.
I sincerely doubt that is true, however.
Your assertion may hold true for piddly little insignificant applications, but anything of any s
Re:In other news... (Score:1)
Thats not what I'm saying. But when my question isn't answered in the documentation, I bet you I'll get my answer quicker by checking the source than I will bitching about the documentation on Slashdot. Rarely do you have to spend hours of spare time to find an answer, a couple of grep's and you're back in business.
Re:In other news... (Score:1)
Well, you're an exception though. If the Slashdot log-in system is too tricky to figure out, definitely stay away from the Slashcode source too.
Re:In other news... (Score:1)
And the cases where they aren't you are even more screwed because you don't even have the source code. For example, I've come across many closed source development tools that have horrible documentation, there was no chance of using the tool without direct access to the authors of it. Whereas I've seen many open source projects that have excellent documentation, easy access to the developers, and well-documented source
Re:In other news... (Score:2)
RTFM == RTFSC ?! (Score:1)
I wrote a howto for a build-a-live-cd-on-the-fly called Intellibuild http://ibuild.livecd.net/ [livecd.net]
iBuild does exactly what I want, but I didn't really have time to read the code, and most people who use it don't either. I realized this and spent hours and hours testing and writing the howto (a bit outdated, atm) and it allows people (who could read the code
Re:RTFM == RTFSC ?! (Score:1)
In some cases, OSS has an advantage because you at least have a fallback of being able to read the source; though this probably only applies to small pro
I want to write docs (Score:5, Interesting)
So how about this, if you have an OSS project that needs some docs, contact me. If I find it interesting maybe I will help out.
Maybe someone should set up a site where doc writers can offer their services and software authors can request to have docs written for their programs. Just an idea.
Re:I want to write docs (Score:1)
http://www.nosleep.ca/jaio/ [nosleep.ca]
I will probably address this, but if you're willing to, it shouldn't take too much time. Let me know!
Re:I want to write docs (Score:2)
Re: (Score:1)
Re:I want to write docs (Score:2)
Re:I want to write docs (Score:2)
GIMP [gimp.org] could also use some documentation help to bridge the gap for Photoshop and PSP users.
Re:I want to write docs (Score:2)
Re:I want to write docs (Score:2)
A lot of project admins in open source are swamped with people offering to do stuff, and never following through. I'll bet if you were to make even a point form overview of what you plan to cover in the proposed documentation and post it to the project's mailing list, you'll get responses.
Re:I want to write docs (Score:2)
His mechanism for collecting user feedback tagged to a specific paragraph and version is so mindblowingly obvious that I wonder why I have never seen it done anywhere else.
Perhaps it's because it works?
Re:I want to write docs (Score:2)
Re:Commenting, too (Score:2)
I've gotten to the point on stuff like this that I try and avoid projects with bad documentation and/or commenting. I figure if they don't want their project to be usable then they probably don't really want people to be using their project all that bad.
Re:I want to write docs (Score:3, Informative)
"The Open-Source Writers Group is a nonprofit organization whose primary goal is to improve the overall quality and quantity of free open-source and open-content documentation. Their web site at: http://www.ibiblio.org/oswg/index.html [ibiblio.org] includes a page where you each register as a volunteer writer, editor, or proofreader for documentation related to open-source projects." - page 41
I have briefly skimmed this si
Oh, the humanity (Score:3, Funny)
But, alas, whining is the quicker path.
Re:Oh, the humanity (Score:2, Insightful)
Has it occurred to you that maybe people need to actually understand a product before they can write documentation for it? Now, who understands better how a piece of software works: the original developer(s), or potential customers?
Re:Oh, the humanity (Score:3, Insightful)
Then again, who usually does a better job explaining how to use it to newbies? The developer or another ex newbie who has worked out how to use it?
Re:Oh, the humanity (Score:1)
Touche.
Re:Oh, the humanity (Score:2)
Wiki for man pages? (Score:4, Insightful)
The biggest problem I have with the man pages, is lack of examples!
--
Original, Fun Palm games by the Lead Designer of Majesty!
http://www.arcanejourneys.com/ [arcanejourneys.com]
Re:Wiki for man pages? (Score:3, Interesting)
Re:Wiki for man pages? (Score:1)
The very first news article on the page you link to says:
Some services are temporarily unavailable
[28-Jul-2004] Due to server problems, some of the services provided by php.net and the mirror sites are not available currently. These include the documentation user notes (including their submission interface), the event submission, cvs account request and mailing list subscription forms. Please be a bit patient, while we sort out the issues.
Corporate Idiots (Score:4, Insightful)
I've changed from doing research at the university to a international company and to my regret and complete surprise, the sysadmins from that company are far from, euh, gifted.
The comporate policy seems to be that anything that costs lots of money must be fine while something which you can download from the internet cannot be anything but bad, inferior and buggy software.
Who cares if e.g. lots of money are spent re-routing corporate e-mail to off-shore server (for a spam solution) instead of installing spamassassin and clamav. But one of the most unfortunate things I have had the bad luck to witness, was an official meeting to evaluate two software packets. One was completely open source and collaborate project while the other one was a commercially branched solution. The meeting had 8 engineers attending a 3 hour meeting evaluating the packet presented by the sysadmins, who had obviously already made up their minds, since the column of the free solution was not even filled out. Finally it boiled down to
The software costed only 250 Euros...
Some (esp *cough* power users *cough* of some commercial *cough* operating system *cough*) users simply cannot grasp the concept that skimming through headers and comments in sources is the best documentation there is. All other documentation is out of date and is certainly not that reliable and often in contradiction with the program and functionality.
This kind of corporate complete braindead reasoning is ubiquitions. Unfortunately, this is corporate IT, not always done by the best and brightest. At least, it really made me to appreciate those good admins out there and you can praise yourselves lucky if you have them...
Re:Corporate Idiots (Score:2)
The comporate policy seems to be that anything that costs lots of money must be fine while something which you can download from the internet cannot be anything but bad, inferior and buggy software.
No, it's all about having someone outside the company to blame when things go wrong.
Oh, dear. (Score:2)
That and $3.79 will buy you you a #1 at McDonalds.
Seariously, that "we have someone to blame when the stuff hits the fan" is the biggest fallacy of commercial software ever. The last time a windows security flaw brought down your entire organization (happend to several clients of mine) did Microsoft do anything about it? Did they fix you up and bring you back online? Did they compensate you for lost time? Lost busine
Re:Oh, dear. (Score:2)
So that is why I laugh so hard when some idiot says an advantage of commercial software is some type of corporate security blanket. Trust me, your vendor doesn't care and won't do anything to help you out of a jam when it is clearly the fault of their lousy software package.
I agree. The point I was trying to make was that management can always use the "but everyone else uses X software", sort of the "nobody-ever-got-fired-for-choosing-IBM" rationale.
Re:Corporate Idiots (Score:3, Interesting)
Did you really say that?! "Hmm... I can't figure out how to do generate a table of contents in OpenOffice. No problem, I'll just read the programmer's comments in the source." What kind of fantasy land do you live in? Give me a manual! Give my father a manual! Don't tell us that we'd be better off reading the source code's comments.
Re:Corporate Idiots (Score:2)
it's ridiculous to think that the source is inherently the best documentation there is. Good commenting will tell you all sorts of information, including not just the data type of the function (assuming you're not using a statically typed language), but also what kinds of values to expect (for any language). It will also explain side effects and all of that.
This stuff isn't built into the source, so you have to write it manually - which takes about as much ef
Re:Corporate Idiots (Score:2)
This stuff isn't built into the source, so you have to write it manually - which takes about as much effort to do properly in the source as it is in an external document, so I fail to see where commenting in the source is so great.
Except that later when someone else changes the source, they have to know to go look up the relevant chunk of some external document and change it, or they have to go to the effort of searching the external document to see if there's something that needs to be updated. Either
Re:Corporate Idiots (Score:3, Insightful)
There are two more ways: The credible threat of an unseen but oft hinted at baseball bat; and the prospect of being sat upon by the 130kg heavy tech writer. I have used both with great success. :-)
Most developers seem to be genetically selected against writing documentation so there needs to be an outside force squeezing i
Re:Corporate Idiots (Score:2)
Documenting the source is great and all, but it's more important to document HOW THE HELL TO USE THE PROGRAM.
Re:Corporate Idiots (Score:2)
If we are talking about user programs that everyone needs to use, documentation is a must; but IMHO we are then talking about a completely different type of program for a completely different target audience.
I would find it troublesome that sysadmins need the same level of documentation of other users (that do not focus on IT).
Re:Corporate Idiots (Score:2)
And further most sysadmins are NOT programmers. comments in source/headers is a completely inappropriate answer. We could hope that most sysadmins might know what source code is, but headers is pushing it.
Remember 99% of these guys read a certification book, passed a test, and now have a job.
Re: (Score:2)
Re:You really are clueless, aren't you? (Score:2)
I really do like Samba's gui (SWAT), but I think even a simpler interface needs to be made. Allowing the users themselves to control what they share in their tree would be great. But nevertheless, there needs to be a better gui on SWAT (one for simple sharing).
I would take that paragraph as a joke (Score:2)
I am interested in doc writing (Score:2, Informative)
I don't feel that I have the ability to write something along the lines of KDE documentation just yet. I would like to start with something small.
If you have an open source program that is lacking in documentation send an email to tjfriese@hotmail.com [mailto] and we'll see if I can't help you out. If your program has an ebuild for Gentoo, that would be a bonus
Time to start Documenting. (Score:3, Interesting)
The app is Jaio [nosleep.ca], which renames digital camera images according to their EXIF data.
That being said, I included very little documentation for the thing, and hardly documented at all the algorithm I used, since to me it was kind of common sense.
I think after reading this article, I'm going to write some more thorough docs, and then include those docs in the help menu.
Thanks Brian, for the inspiration!
Re:Time to start Documenting. (Score:2)
After taking a look at your project, I have a small suggestion for you. It would be really helpful if you would put a short explanation of what your program does both on your web page and in your program (i.e. "This program renames images according to blah blah blah..."), . Right now, you can't tell exactly what JAIO does. It wasn't until I read this post that I was able to figur
Code docs as well. (Score:3, Insightful)
I actually haven't run across major usage documentation problems like the author of the article did -- I have been able to install and run many of the programs I want to, without significant trouble. The problems I run into are when I actually want to dig into the code to change something. I am usually bewildered by the size of the project and I don't know where to start.
Documentation is good. I like writing documentation for my code (and I feel like I'm somewhat rare). But it's something that I naturally do at this point. I don't consider it a 'chore' or anything like that -- in fact, I enjoy writing docs for my code that I understand, in order to communicate this understanding to others.
I think that code documentation, not just usage docs, is a core part of the open source development model. If you are the only one who can understand your code, then chances are that your project will die if you stop maintaining it. The mental model is very important in programming, and others' capability to replicate your model in their minds will help them write integrated, less buggy code for your project.
Brian Jones (Score:3, Interesting)
I haven't had a problem with major projects.
Is it largefile aware?
I really have seen very few closed-source packages that include this in their documentation, either.
Is it scriptable?
I can't think of any open-source packages that are scriptable that don't document the point that they're scriptable.
Most OSS CLI software isn't explicitly "scriptable" because it can simply be easily run and interfaced with from scripts without requiring an internal interface.
I have refrained from naming names here. It would serve no useful purpose, as my sysadmin colleagues can probably think of exactly the projects I'm talking about (as can the respective coders).
Actually, I'd infinitely have preferred that Brian *had* named the names of the OSS projects that he found at issue, and listed some concrete problems. Then they could be addressed.
The bigger problem for you coders, really, is that there are usually 20 different packages on freshmeat that all do the same thing. Of those 20, probably one or two have real-life, usable documentation.
Your problem sounds more like a lack of comparative reviews to assist you in evaluation than a lack of documentation.
This honestly sounds like the sort of problem you get if you start trying out "mp3 sorters" or "IM clients". I'm dubious that this is a severe issue with, say, webservers.
While I'm posting, does anyone have any idea why Slashdot is changing colors on me like mad? I've seen a rather pretty but less usable gold-and-white theme, and I'm currently posting in a black-and-white theme that says "Don't fear the penguins". CmdrTaco put up a test story on the main page yesterday -- what's going on at Slashdot?
Re: (Score:2)
Re:Brian Jones (Score:1)
Re:Brian Jones (Score:3)
Re:Brian Jones (Score:4, Interesting)
mysql (almost all the documentation is wrong, and I mean the simplest stuff is wrong, like working with authentication). They have lots of documentation, but most of it is inaccurate, out of date, and in many cases was ALWAYS wrong. They rely too much on the ability of users to comment on given pages of documentation. But those users are wrong half the time, and even when they are right their contributions don't seem to ever be added.
Apache, dear god just look at it. Their documentation is basically a quick reference, they list all kinds of options and generally out of context. Have these people never heard of tutorials?
Bind... bind is scarey as hell, you find conflicting and inaccurate information EVERYWHERE not just on the website. For instance, look for information on how to setup reverse lookups. You won't find any actual tutorial type information at all, explaining simply how reverse lookups work and giving a couple examples. Nope, what you'll find are lots of people posting new information about old versions of bind. They give incorrect syntax that simply doesn't work almost every time.
Thinking about it, I can't honestly say I've EVER found a bind example on the web that worked without modification. From ANY source.
I've yet to find a ftp server with good docs either, again the same problem. In the case of ftp servers they seem to have an obsession with large anonymous ftp (aside from universities and large software vendors who actually wants to do this?).
If any other option they give the ability to have users log into their system accounts home directory, talk about a pain in the arse to manage and keep seperate from other services. I suppose if you were doing web hosting this is what you'd want, but not for anything else.
Most things assume that actually using the software is obvious, or the other way, they assume you've had no problem installing.
Very few give configuration examples. Some sites give a couple limited examples but don't give examples of usage for the config options. Some give the config options but no configuration examples, like apache. Some do either of those or both but don't cover how to install the software.
COMPLETE Documentation is needed, that covers everyone from complete novice and idiot who nothing nothing about the app or the OS to power users who know nothing about the app. Even advanced documentation should be written from the perspective that the user knows nothing about the app.
Because after all an advanced user, who knows alot about webservers and nothing about apache, is going to be looking at adanced topics the first day they are playing with apache.
The docs should take you from novice to guru, include tutorials, include a hand hold through installation.
References are good but they don't replace the need for any of the rest of it.
The docs should also always apply to the latest stable version, if the docs havent been checked and updated, then the new version isn't stable yet. The docs should be considered part of the release.
Re:Brian Jones (Score:2)
I confess that I've never seriously used mysql. I was impressed with th
Re:Brian Jones (Score:2)
SSL would be a fine example then, it's a trivial requirement of pretty much everybody who is setting up a webserver, even if they aren't going to buy a cert pretty much everybody needs ssl for something.
"Remember that, until the Web got big, anonymous ftp was simply how you distributed *everything*."
Althou
Re:Brian Jones (Score:2)
Somehow, I managed to cut out what I was typing. I was trying to write that back in the day, almost nobody bundled SSL, so there were few people using it, which was almost certainly a factor in good tutorials not being around.
99% of the time windows applications don't fail to install in the form they ar
Re:Brian Jones (Score:2)
Read what you just quoted there again and think about it. Also RPMS are a packaging format, not an end user installer. Almost no project distributes RPMS or any other binary format, with or without an installer.
Re:Brian Jones (Score:2)
Re:Brian Jones (Score:2)
Apache:
Here you will find a nice webserver, with source downloads only and a handy windows installer... that is useless since it lacks ssl I might add.
http://httpd.apache.org/download.cgi
Bind:
Good old source, and only source.
http://www.isc.org/index.pl?/sw/bind/
Linux:
Again we have a choice, between source, and source.
http://www.kernel.org
Dvd::Rip
On this one I admit he does helpfully link to
Re:Brian Jones (Score:2)
May I ask why you feel that this is the case?
Re:Brian Jones (Score:2)
A user needs to be able browse the web for "linux webserver" or some such, find something he likes and click on the official site for it, and download + install that thing.
Even when the official site points to a 3rd party with rpms for instance. There is no quality control, nobody who works with the application is checking those packag
Re:Brian Jones (Score:2)
Yes, but the larger ones are becoming effectively so. I only very rarely use anything not packaged by Fedora or the associated repositories.
And short of random installation, you really never find things browsing through a list like you get with yast or synaptic.
[shrug] Maybe not, but you just type apt-get install [program name] if you want to install a program.
Even when the official site points to a 3rd party with rpms for instance. There is no quali
Re:Brian Jones (Score:2)
That assumes you already know what you want to install. And your right, most things you can name off the top of your head, will in fact be in the repository (assuming you can figure out what it's listed under, often it's not the programs name or some odd variation of it)... at least with debian or 3rd party repositories with fedora (not much is actually included with fedora). The problem arises when you
Re:Brian Jones (Score:2)
Well, here's pretty much the process I recently followed. Way back in the day, I used to use yafc -- it supports sftp and a large number of authentication protocols that I use. Yafc was discontinued by the author. I'm not a huge fan of ncftp, which has been Red Hat's standard "enhanced" CLI ftp program for a long time. I googled around, and read a list of CLI ftp
Re:Brian Jones (Score:2)
Aye we've wandered a little bit. I don't think either of us are trolling, we simply disagree. But I don't think either of us is convincing the other either.
Wow (Score:2)
1. Read the doc
2. Install it on a test box
3. Test it
Impressing, I wonder how much ppl do the same.
Heck why do you think most products comes now with little or no printed documentation ?
Documentation Is Needed, Though (Score:4, Insightful)
Re:Documentation Is Needed, Though (Score:2)
Why? Not everyone is an idiot, but most people aren't "fairly smart, experienced". Most people are fscking stupid and admins are no exception, users are the very definition.
Re:Documentation Is Needed, Though (Score:2)
Re:Documentation Is Needed, Though (Score:2)
The documentation is for both experienced and inexperienced users, and assuming experienced users know ANYTHING about the program itself before reading the documentation is absurd.
Full documentation, and no I'd completely disagree, it should NOT be a book sold by a 3rd party.
Re:Documentation Is Needed, Though (Score:2)
Unfortunately, the vast majority of software projects out there have the programmers themselves writing the documentation. It would be nice if things were otherwise, but that's how it is, and that's probably why documentation is such an issue right now.
Full documentation, and no I'd completely disagree, it should NOT be a book sold by a 3rd party.
You're misreading what I said an
Re:Documentation Is Needed, Though (Score:2)
"Perhaps professional authors would like to join the open source movement and start authoring for OSS projects for no pay. I just wouldn't hold your breath waiting for that"
Professional programmers work on open source projects, some with and some without pay. What on earth makes you assume these things have to be done without pay?
In many cases there is a commercial conflict of interests on open sou
Re:Documentation Is Needed, Though (Score:2)
You do realize that authors today do this very thing? It isn't a matter opinion that they do: it's a fact. They learn the hard way, the way experienced computer users do, and by interviewing users familiar with the software and even the developers themselves. Then they author something more digestible for inexperienced users.
Professional programmers work on open source projects, some with and so
Re:Documentation Is Needed, Though (Score:2)
I don't know many experienced computer users who do it that way. Most I know beat the software with a stick and if all else fails check the documentation, if that fails check google. If that fails check other engines. If that fails, find other software.
Dear god, the very idea of communicating with other users BEFORE you are knowledgable enough to hold your own is offensive.
"How do yo
Re:Documentation Is Needed, Though (Score:2)
I don't know many experienced computer users who do it that way. Most I know beat the software with a stick and if all else fails check the documentation, if that fails check google. If that fails check other engines. If that fails, find other software.
This is precisely what I said: most experienced computer users learn the hard way. This is how authors do it and then they write documentation that is easier for people to un
Re:Documentation Is Needed, Though (Score:2)
No you defined the hard way as talking to other experienced users and the developers.
"What is your point? Have you not read anything I've written?"
The point being that is exactly how you stated these authors are supposed to learn. The hard way I defined is impossible since there is no useful documentation (at least not th
Re:Documentation Is Needed, Though (Score:2)
No, I said they learn the hard way AND by interviewing experienced users and the developers. Here's what I said, verbatim:
Books on programming languages yes, languages change slowly overall. Individu
About documentation (Score:4, Funny)
1. Add a 3-line FAQ for expected "bugs"
2. Add "We need documentation authors" to README
3. Wait for documentation to be written when you are finished with v1.0
4. Delay documentation since it would break with the current v1.1 development
5. You don't bother doing the documentation, since you've allready documented most in the source.
6. When it works, you just publish the source and hope somebody else will do the rest.
7. Make a website, create a logo and start having a nice time making design and stuff. When finally creating the documentation/index.html, just add Under Construction, since what you really want is a even better logo.
8. Write some complex documentation, and hold back the real tutorials and publish them in a book [amazon.com].
9. Spend some time with emacs, to finally understand that it sucks to write documentation when you have to think of line-breaks in a text document.
10. Include an myfile.conf.example which you think will cover most questions anyway. Do forget on purpose that many lines need linebreaks at end of text, even if it's the last line. And also forget to add that TAB's are not supported in your
Linux (Score:1)
Re:Linux (Score:1)
That is called dependency hell. Fortunately now we have great tools like apt-get, yum, portage, and others. So installing a package can be as easy as apt-get install package_name. I think the easiest way for you to try it is burn a knoppix 2.6 iso.
It's the UI, stupid! (Score:1, Redundant)
tough to write good docs (Score:3, Insightful)
I immediately doubled the estimate. Why? Because you are basically writing the logic of the app all over again, except in this funny programming language called "English". And when you update one you have to update the other. Not to mention you have to update your unit tests too (which is another thing most programmers don't do).
I'm not trying to make excuses or saying that we should skip documentation, it's just that it doesn't "scratch the itch". I don't believe that open source exists because of altruism, but because somebody solved their own problem and didn't keep it from the world. So we need folks who are truly interested in documentation (like technical writing geeks).
As open source grows we need to find all sorts of folks: technical writers, usability experts, designers, artists, testers.... we should also not be afraid to hold "fundraisers" to hire an outside team to do this. Wouldn't it rock if Mozilla, KDE, Gnome, etc., had a *thorough* going over with a talented usability team?
Anyway there's one concrete piece of advice I can give any open source programmer, especially if its not a gui-based tool: PUT EXAMPLE USAGE ON THE FRONT PAGE OF THE WEB SITE!!!
This annoys me to no end. Too many sites just have blocks of text describing how great their stuff is.. but no example of setting up a config file, running it from the command line, etc.
I would love to see a step-by-step up and running document, nothing fancy. Show some examples of what your config files and so forth look like. How about screen shots of command line operation? If it's too complicated to show in a few pages, *simplify it*.
The quicker I can get your program up and running, and the less work I have to do, the less I have to hack in my existing configs and so forth, the faster I will be sending you patches.
Positive example: The awesome Ruby on Rails [rubyonrails.org] framework has a setup *movie* showing exactly how to go from zero to app in 10 minutes. I wish all projects had something like that, and more importantly, I wish all projects were SIMPLE enough to demo in a few minutes.
Negative example: I was wondering if Perl's Template Toolkit [template-toolkit.org] was the right template system for me. I was looking for a very basic kit that could mix Perl directly with HTML (a-la PHP) with no fluff and bloat. I couldn't see any example on the front page and after a minimal amount of searching, I still had no idea what it was like to actually *use* the damn thing. Just bullet lists of features (which are shared by pretty much all similar systems).
So, as a first step down the road of good documentation, try this user-focused idea: give some examples up front.
I have only one thing to say... (Score:3, Funny)
He's half right (Score:5, Insightful)
* 90% of the documentation does not exist
* Of the remaining ten percent, 90% is obsolete or inadequate
* Of all the documentation, the remaining 1% is written in a foreign language you cannot understand.
We know about the first and third points, but on the second point, it's either missing examples (i.e., man pages, as another user cites), or just tells what you can do with it and little else without bothering to take you through the steps (much closed source), with explanations on what certain functions do that are vaguely important.
To note, the "law" was published in Steve Oualline's Practical C Programming by O'Reilly books. I modified it slightly - the third point notes "Chinese", but there's a good probability that somebody reading this can read Chinese. =)
Documentation is bad... (Score:2)
This would encourage better design (Score:2, Interesting)
I know it's not 'fun' or 'easy', I code in random bursts too, and my first versions are always "unreadable but it works great!", but if I use the app at all then I do a complete rewrite for the v2.0, since the v1.0 was more of a design-as-you-code exercise, and the resulting
Gentoo as an example (Score:2)
Now, if it wasn't for Gentoo's superb documentation, the number of people who have Gentoo installed would be in the hundreds (if that) not the thousands. Because of Gentoo's excellent documentation, it is possible for a
Re: (Score:2, Insightful)
Re:assholes (Score:2, Insightful)
Not every developer's goal is to advance OSS. I have no data to back this up, but it seems to me that many probably just wrote a program to do something they wanted. The fact that they released it in hopes that others may find it useful should not obligate them to cater to every person that feels that they have the right to have their hand held while t
Re:assholes (Score:2)