Distributions have at least half the blame on themself. They tend to patch stuff to suit to their own way of thinking.

Moreover, even distributions which claim they tend to use pristine sources from developers site (Debian comes to mind) have highly patched packages (in Debian case they fail to upgrade to clean fix releases x.y.z => x.y.z+1 but backport them)

And don't even get me started on bug-tracking systems... I really treat it as a gamble and use it only if I have plenty of patience. Non-answering for weeks, WON'T FIX solutions, works for me, and all that fun stuff...

Which brings us to documentation... What is the best solution to writing them? Man seems great for text based applications, but fails miserably for GUI ones. So is HTML next best thing? Since PDF is still proprietary... Should we abandon LaTeX in favor of DocBook?

Absolutely! I've often said that one of the biggest problems with Linux is lack of easy-to-understand, readily-available docs. And it's getting worse in a way that this article didn't point out -- out-of-date, obsolete docs. I recently tried to get a touchscreen working on Linux and went through hell. Via google, I found at least half a dozen "instructions" to get it working. Many of the instructions talked about editing xorg.conf. Oops. Recent versions of xorg use hal to setup hotplug devices (like a USB touchscreen) instead of xorg.conf. Other instructions talked about setting certain "flags" in certain drivers. But again, how you do that also varies according to what versions of Linux, xorg, and drivers you're using. Many of the described "solutions" I tried did nothing to solve my headaches. And I hear that HAL is getting replaced soon, so the current "solution" I've used will probably no longer work at some point, and yet it too will be "documented" on the web somewhere where someone will stumble upon it via a google search, waste lots of his time trying to get it to work, and then throw up his hands and go back to Windows. Linux folks need to not only learn to better document things, but also clean up their forums, mail lists, faqs, what-have-you to get rid of obsolete "docs/solutions" that do nothing but confuse and frustrate endusers who are using software that no longer is applicable to the obsolete "solutions".

It's not realistic to expect everyone to support Ubuntu + Debian + Fedora + openSUSE + Mandriva. I have enough trouble fixing and documenting all the regressions every time I update one distro. I keep a couple of barely-working alternate distros around for testing, but if I had to keep five of them fully updated I'd never have time to do anything else.

Better project documentation would help more. If developers are too busy or can't be bothered, why can't we talk non-developers into helping with documentation? I hear a lot of people complaining about lack of documentation but I don't see a lot of those people going on to write docs. (That's not aimed at Carla, who has written enough user howtos for an army of users.)

But to make that work, projects need to be welcoming to non-coding volunteers, and accept their contributions instead of shuttling them off to some wiki where documents go to die. Being responsive to bug reports would be nice, too. Wish I knew how to make that happen.

Finally, jg has a great point about the problem of obsolete docs on the web. Being clear about versions can help; write early on the page that this is a fix for FooApp 1.0.3 on Ubuntu "Kinesthetic Kangaroo" or whatever, and use those version numbers when you're googling. I've found that very helpful.

Carla,

How about sharing your methods of making a good living writing Linux docs. Personally, I didn't know this was possible. If other people knew this was an opportunity, I bet you'd have a line of enthusiastic applicants.

You blame the developers for hiding information, then you hide information. Why don't you tell us what is the application?

As a first time Linux user, I ran into the same thing. I first tried Debian which seemed to work the most bug free on my computer. The sound worked but not system sounds. So, I Googled. Evidently, many others were having this same problem. In reading a bug discussion, it was suggested to the user that he was a pretty good coder and should fix it himself (if he wanted it fixed).

No doubt, I was really impressed. I eventually switched to another distro (less buggy and better working).

Recently, I am trying to fix a problem in Ubuntu on my laptop. I can switch the mouse buttons. I'm left handed, but that doesn't work on a touch pad. I did some Google research to find which file I need to edit (using the file-system-hierarchy), but this distro does not use such a file. There is no documentation on Ubuntu's file system and I don't want to scour the wiki that EVERYBODY thinks is a godsend to answers. Does anyone ever pack their HTML documentation in a PDF anymore? Is that too hard?

I would like to find out how Linux boots up from scratch. What loads and runs in what order and what is looked at (file wise). I know there are docs for that, but where?

http://www.gnu.org/software/hello/manual/libc/Exit-Status.html

http://tldp.org/LDP/abs/html/exit-status.html
almost every c program has a return 0 at the end of the main function and 1 or whatever if something went wrong.
The mysterious application should has an option for being more verbose -v or something but u can't expect developers to teach ultra basic C in the man page of the program.

I ansolutely agree with the article.

Even if there is written documentation, the documentation is not targeted at the right audience; there is no differenece made between between enduser documentation, system administration documentation and developer documentation.

It happens frequently that as an end user I am asked to look into the sources, which is by defintion a wrong attitude.

A lot of documentation can only be understood if you know the program very well. But as a newcomer to the program there is nothing to get you started

Just yesterday I tried to setup Dansguardian, a open source parental control system, which has a lot of useless documentation on its wiki. What I needed is a 2 page document explaining the use case that 95% of the people are interested in: how to install the system and how to define white lists and black lists for the user accounts that need to be controlled. But that document is not existing. So I dropped Dansguardian because I could not afford the time and effort spent reading the whole wiki looking for bits and pieces that might be useful to get it up and running

Carla,

The reality of any system, whether FOSS, propriety or other is that documentation is HARD work to 1) get right, and 2) to keep maintained. I have been in the industry for about 30 years and in that time, I have seen few occasions where the documentation was barely adequate let alone superb.

I have written written technical specifications, functional specifications, user guides, user cheat sheets, etc and have generally had the comments come back about how extensive and detailed and good it was. This has all been paid for by my clients or employers at vatious times. To get it right takes a huge amount of HARD work and in reality most of us would more than likely shoot ourselves in the head than try to do the job properly.

Compared to a couple of people I have come across over the years, I would classify myself as passable - they were geniuses for doing documentation. But people like this are very few and very far between. Compared to many others, I have been well ahead of the game. I will do documentation under two circumstances, 1) being paid for it or 2) I really love the project I am involved with. I won't do it otherwise, it is just too much HARD work and just not fun like developing is.

Until a way is made to make it fun, don't expect good documentation to be the norm for any system (no matter whether it is being paid for or not). Even most of the documentation you purchase is not up to scratch.

Be thankful, that with FOSS software, you can at least look at the source code to find the source of error messages.

As is noted in akk's comment, you have written many user guides over time. You then must realise just how hard that has been to get right and keep maintained. If you don't, then you are one of those geniuses mentioned above and you are then worth your weight in gold bullion.

regards

Bruce
Australia

From a developer perspective, it's not easy to write documentation.
Which one do you need? a wiki? a README? a 10 page user manual, a 250 page book? In wich format? plain text, HTML, ODF, man, info? How to start? What to talk about? What to ignore? How to structure it?

Simply crying "better documentation!" is not going to fix it. I would be infinitely more helpful if the people better skilled and with the experience could help and guide the rest of us.

Also, distributions and/or desktop projects can certainly do a whole lot more. Having guidelines for new developers, and rewarding (with more visibility, for example) those that follow them.

Absolutely correct! I've been in IT for 40 years now and Linux has the absolute worst documentatation I've seen. Followed by Unix. Man pages? Puleeeze! I find them totally baffling in most cases. The odd example could go a long way. But no, just endless diatrabs about what this or that parameter does but no example. So I try it and the command throws an error.

My projects are documented clearly at every level. Yes takes time. But mostly saves me sleepless nights answering support calls. Important if you are on perpetual call as I have been for most of those years. Also if you have to describe how to use something you have to check that it works as expected, and lots of times this points out problems that you can then correct or improve

I use Linux as my primary OS at home but XP at work (no choice). While no paragons of completeness MS docs are better in most cases.
Too bad the OS isn't.

Me too. As a former programmer, I spent endless hours writing lucid documentation, which nobody ever read. Or sometimes they read enough to find my name and contact info, and called me to explain "how do I ?" or "why does it ?". Literacy versus laziness.
Most galling was a project where I was assigned a very stupid tech writer who was too dumb to figure out what the software did, or how it worked, and told me to re-write the software so she could understand it. Never mind functional specs, she was more important.

For saying this I will probably get (yet) another ad hominem from ûberprogrammer and ûbermensch Rainer Weikusat but good documentation/error messages is the touchstone of good, professional work. And that includes either having meaningful messages or documenting error conditions. In mainframe times you got something like IEC151-I D37-04, you took a look at then error code manual and you knew why the OS had killed your program.

i would say documentation, beyond simple get up and go stuff, stink, no matter if its linux, windows, or some other random digital object.

maybe if the topic is generic enough, there is a "black book of spells" to be had from specialist publishers. If not, good luck figuring it out.

People here say that writing documentation is so HARD, as if it was as hard as trying to lift a building. Really, this is ridiculous.

First of all, nobody is asking for 100% super in-depth documentation. For the start it would be good to have at least some basic instructions for installation. Many FOSS projects don't have even that. You go to their page and it says - download source and compile.
You dld, compile but it says - Exited with error 1. What now?
It is not that hard to write a couple of pages of text, listing the needed packages and what might go wrong. There is no need to explain each menu. Lots of documentation is writing the obvious - click on the menu, then click on Next - duh. I would rather see some Troubleshooting stuff.

Second, maintaining at least basic stuff is also quite possible. As a user I don't care about what variable was fixed when, as they often write in History of development, I want to know whether it compiles on the latest Ubuntu.

I guess what is needed is some sort of standard. Linux world is very diverse. But atm I see no easy solution.

What Linux needs is a universal standardized accepted package format.
Know a lot about .deb and .rpm and they can be improved somewhat. Rpm5 looks pretty good from what I've seen so far and makes a good candidate.
At least there is one project looking into the matter:
http://www.openpkg.org/

Package databases are good but the distro's package managers should be more neutral and in a distro 1 manager for all formats, tasks. More integrated.

Documentation about technical problems in all sorts of problems is below what it should be. Simple things are explained, a little more difficult than the basics where sometimes things go wrong. Then there doesn't seem any documentation.

Now for software, there is one thing that can help.
Autogenerating documentation by having special kinds of comments in source code. This way, the place where you change code, your documentation changes with it when you hit generate. Much better but still. There should be some good tools to make documentation much efficient.

The assessment is spot on. I'd rather that the Linuxes take a look at OpenBSD's documentation. One of the difficult things about OpenBSD is getting used to how GOOD and thorough the manual pages are.

The linux distrous could be like that with little effort. If there is some insurmountable objection to using the manual pages, then at least drop "info" files and go to a subset of HTML 2.0 with a one document per object policy.

All Linux distros are different. All programming teams are different. Instead of issuing a blanket statement such as "All Linux documentation is horrible," try looking at the documentation of other distros than the one you're basing this statement off of.

http://wiki.archlinux.org/
Arch Linux has possibly the best documentation I've ran across, excluding some of the *BSDs. Wikis aren't always bad. Granted, I think most of it is user-generated.

I'm sorry, but I fail to see how this is any different than windows. Have you read the manual that comes with windows or your PC? Have you read the manual that comes with Office? The fact that there are so many books out there for windows users that are not written by Microsoft should tell you that documentation is lacking there as well. And to be honest, most people either use Google or ask a friend when they have windows issues.

Also, stating that Linux is lacking documentation is like saying the Windows Kernel is lacking documentation. What you should be mentioning is the lack of documentation for distro 'X', and even then you would get no more or less than what you get out of the box with windows.

You also have to take into account that a basic windows installation comes with virtually no real applications, while a well known Linux distro will give you everything you need including most things beginners don't want. Those apps need their own documentation just like apps for windows.

Bottom line is most basic computer users will not look at the docs anyway. Now, if you want to argue about the quality and availability of documentation for specific apps and distros, then you have a story.

@Big Joe:
Strange I would love to find man pages in windows. I personally find the documentation in Linux to be suffice and I have only been using it for the last 4 years (in a professional capacity).

@Carla:
Yes that is a wonderful error but windows errors are as bad if not worse. As was explained above generally a commnand line app will return 0 for success and non-zero for a failure (again generally 1).

In general though I find Linux documentation miles ahead of windows in the majority of areas.

@sha: I think you missed the point. By a mile. She knows that "something went wrong." But what the hell good is that if you can't tell *what* went wrong? Do you think that when the Challenger blew up, NASA got a response code that said, "something went wrong"? Sheesh.

@zgdsgsdg: re package format, way off topic. The source code documenter you're looking for is called Doxygen (or javadoc, or ...many others). But that is absolutely not the answer. Doxygen source code comments are great for documenting the API, which is what they're intended for. But that's developer documentation, not user documentation. It's silly to think of putting user level howtos and tutorials in the source code.

I do agree that good dev documentation is sorely needed too, but that's not what this conversation is about.

If people are scouring through the documentation for your contact info and then contacting you directly, they didn't find what they were looking for in the documentation. That is a problem with the documentation, not with the people.

For several weeks trying to understand how to use tcpdump from the man page, I thought it was trying to tell me to write bytecode in order to figure out which packets to filter. A single example somewhere useful (say, at the beginning or end) would've been quite useful. I eventually got what I needed from a tutorial found from Google.

I've had similar experiences with just about every single man page I've ever looked at. They're all universally useless - they're not addressing what the first 95% of people want to use the program for. They're addressing the developers who wrote the thing in the first place.

As long as there ist no quality standard for linux programs that defines documentation ...
All this said here makes clear that it have to be defined or there is babylon or "what we are talking about?"
It's up to Ubuntu + Debian + Fedora + openSUSE + Mandriva to talk about it and to make contributions to the projects/packages they include in their product.

Most open source apps have a very small target audience: the programmer(s) that wrote them. There are a few that don't, but they're often supported by a larger organization (Eclipse, the Ubuntu-sponsored apps, Open Office). The reason developers don't write documentation is because they are done when the code does what it wants. Documentation is superfluous, since the entire target market already knows how to use the app.

Now, if we're willing to start paying developers to write apps, I think that will change. But until then, you get what you pay for: someone's hobby written to scratch an itch, and maybe a little more.

I think some developers have to develop patience. I'm a developer (and Linux user) and feel ashamed at the lack of patience with new users. Don't come complain if buggy evil Windows takes over their hearts...

I agree with all you said. I think this has to be put in perspective tough. I was, and am still, forced to work on Windows and I find the applications on windows lacking much more in the documentation department, try googling a random windows-application problem, chances are that you find only other users having the same problem. Also there is no decent bugtracking for windows tools.
I'm using Linux heavily for everything, but I have seldom encountered completely missing documentation and there is almost _always_ a homepage.
Just my 2 cents.

The comments above really touch on a lot of good points. My latest experience with Linux involved Kubuntu. I had several issues similar to the ones described above, and like other readers found too many useless how-tos that only wasted my time. In the end I just wiped that install and replaced it with FreeBSD 8/64 which just received its first 3D graphics driver from Nvidia yesterday.

As a developer I personally would not even want to touch Linux, especially if coding in C or another native language. There are so many distros and things change so fast that there's no hope my app would work on more than a couple distros or work for very long unless it's constantly updated. My solution to that is to use FreeBSD where everything is consistent and backwards-compatible (like Windows for those of us who are not fans of Windows). The only trouble I have there is with packages coming from the Linux ecosystem which suffer from the problems mentioned above.

The best fix for all Linux distros, in my opinion, would be to use a language like Java or .NET which can itself be tailored to run on the particular distro and which will later run any software written for it. There's no library hell, no configuration files all over the place, and no days wasted trying to resolve a simple issue. Otherwise the system is a pain to use as it is, and even developers are setting themselves up for failure unless they choose to appease the differences of dozens of different distros.

User documentation is not a job for developers but code documentation definitely is. Very few developers have the skillset necessary to create good user documentation. Good user documentation consists of:

• an introduction that explains what the application is, why one would want to use it and what one can do with it.

• glossary (if there are terms unique to the application that the reader needs to understand in order to use the application).

• system requirements.

• tech support contact information.

• installation instructions.

• documentation of the most common user procedures and step-by-step instructions for doing them (screen captures in this section can be very useful).

• a thorough description of the user interface (for GUI applications), describing each menu item, toolbar button and dialog box.

• troubleshooting

Once all this documentation has been created, the next step is publishing it. With proper tools, this entire documentation set can be published as:

• HTML
• Wiki
• PDF
• Print
• Help file (*.chm, etc.)

Poor documentation in professionally developed products comes about because management and the development team often don't have an understanding of what good documentation actually is. All they're concerned with is being able to put a check mark in the box that says "Documentation" on the project plan at the lowest possible cost. From their perspective, having a developer or intern throw together crappy documentation is sufficient. What they fail to take into account is that good documentation can reduce support costs, thus paying for itself.

Despite the conventional wisdom that says "anybody can write", it's not true any more than it could be said that given a pile of man pages anybody could be a developer. I've inherited any number of absolutely dreadful "manuals" written by developers or worse yet, interns. A big part of my job over the years has been taking those source documents and overhauling them into documentation that users can actually use.

I have tried Ubuntu. It installed fine - but I had very-very simple and average HW, without any exotic and funky peripherals. Just a mouse, a screen, an average Dell everything-on-the-motherboard machine. Fortunately, I installed it as dual-boot with Windows. A few weeks after, I installed a new video card - a run-of-the-mill Nvidia card. Windows saw it right away and installed the generic drivers for it. I then installed the drivers that came with the card. No pain. Then I booted in Ubuntu and... no luck. There was nothing on the screen. No GUI, no messages, nothing. Just a prompt, and lots of blank screen. I have booted again in Windows and I started to google for solutions. As soon as I found "a solution" I rebooted in Ubuntu to try it. Of course, it did not work. Lather, rinse, repeat. After about 4-5 long evenings spent on this #(*&@# I finally gave up and went back to Windows full time. The answers I got from the Ubuntu forums were a) few b) slow in coming c) failed to understand that c1) this was my first ever Linux experience and c2) I only had the prompt, and nothing else and d) probably incomplete and/or inaccurate, since none solved my problem. I agree - if I were a Linux expert user, I could probably solve the problem in one afternoon. Even though I am a good .NET programmer (so no noob with computers) I could not make it work in Linux. Think of it this way: I only had a blank screen, and I didn't event know how to start some kind of text file manager in Linux - let's not even talk about which config files to change, and how. I don't live in my mother's basement, so therefore my time is limited. I simply can't afford to waste days and more days on this kind of things. I would have liked some documentation, instead of "advices" like (and I'll invent some acronymes here, 'cause I don't remember the actual text) "mmsod uhxs.txt, then compile". Huh ? And yes, this relates indeed to the fact that Linux only talks to a small hobbist audience, with lots of time on their hands. It is ages away from your average user... I would have loved it to be otherwise, of course, but in the meantime, thanks, but no thanks.

I am not a UNIX/Linux newbie; I worked on high end kit for over 12 years. But at times even I get a little lost with Linux documentation. No wonder newbies struggle.

My favourite hobby horse is Linux and the Load_Cycle problem which the great and the good of the Linux world seemingly ignore.

The biggest myth of the open source movement is that "anyone" can contribute.
In practice, to be able to make even a tiny contribution to an open source project one has to have infinite patience to learn the idiosyncrasies of the project AND be an expert in a variety of technologies.
And the reason for all this is the lack of detailed documentation AND tutorials. For an open source project to gain traction, it should have human-readable documentation.
Unfortunately, this simple concept is lost on Richard Stallman, Linus Torvalds and all the other open source evangelists.