Linux Bug #1: Bad Documentation (part 2)

Carla points out that an actual book — you know, the kind made with paper and glue — can be enormously helpful.

One of the reasons I recommend Ubuntu to potential users isn't so much its supposed awesomeness but the presence of more than a few really good books for beginners on how to use the system.

As for me, I'd be more burnt toast than I already am without Carla's "Cookbook."

That aside, I'm willing to put some work into documentation for a FOSS project or two ... but where do I start?

Buy lots of books! Often! :D

When I am out from under my current obligations Steven, I have a couple of FOSS projects in mind to help with docs. I like them a lot and they help me, so I want to return the favor. I suggest pick your favorite, ask them if they want help, try to get a vibe if you can get along with them, and away you go. I think a logical starting point is looking at what they have and how it's organized, and how much can you collect from lists, Wikis and forums, and whip it into some semblance of coherence. I think anymore the bigger problem is organization.

Quoting:... but where do I start?

Start with applications you love and use often.

I have a bookshelf filled with helpful technical books. I even have one of Carla's. There are times when having a good reference at hand is a lot easier than Google.

Google usually works if you don't value your time, don't mind following potentially unreliable advice that can destroy your system, and don't really care to learn why your first six failures were failures.

I remember reading something about an author complaining that Google has destroyed the book business. I disagree. I buy/check out books all the time.

Great point, bigg. I don't know how many times I've Googled some esoteric problem only to find mailing list posts and forum posts by other people with the same problem... and absolutely no solutions.

> I don't know how many times I've Googled some esoteric problem only to find mailing list posts and forum posts by other people with the same problem... and absolutely no solutions.

Too many times to count, especially for Windows problems. :(

A friend got bitten by a Vista bug recently. The machine boots fine, everything comes up, but the mouse won't click. Well, actually the mouse clicks fine, but the system just ignores it. The solution? Hit A-C-D, select the task manager, then exit it. Then everything works. Dozens of people have reported the problem, no one has a reliable fix. Some of the suggested fixes work for some users, but none work for everyone. Even a complete reinstall of Vista doesn't always seem to fix it. I had to give him back his computer, tell him the work around, and tell him I couldn't fix it (no charge, of course).