Agreed; I've installed many distributions, and Gentoo was arguably the most difficult and time-consuming to install - but Gentoo's thorough documentation made it the easiest in terms of understanding the complete process of installation. That documentation made what would have been a Slackware junkie's worst nightmare into an easy step-by-step recipe. But then again, I had already installed several other distros by the time I did Gentoo, and knew my way around /etc pretty well. Gentoo is definitely not for the Linux newbie (documentation or no), and I hope you were never led to believe otherwise

I also have to disagree about programmers writing manuals. I think it's essential that the programmers write most of the important documentation. They may not do it well, but I think they are the ones most qualified to do it. Someone else, such as an experienced user, or a copyeditor with programming experience, can polish it into a real user manual. Computer software is code; nobody understands the code better than the programmers.

I think your complaint is that some programmers don't like to document, or don't do it well. This probably comes down to a shortage of people willing to volunter work on documentation from a user's perspective. Some developers do put in the extra effort at documentation (I've tried my best to do this in my own projects, as I believe all conscientious developers should do). But I, too, have suffered from documentation negligence in other projects. Whether a program/utility is well-documented plays a large part in determining whether I'll use it. Programs that I find useful, and that have good documentation, I often end up using frequently (and recommending to others). Programs with poor documentation get a short trial run, and are uninstalled. Programs with no documentation, I usually won't even download. Sadly, such is the case with a large number of open-source projects.

Moral of the story (to open-source developers): Documentation can make or break your project. Make sure your documentation doesn't suck.

Amen...but it should be no surprise that there is more to it than simply programmers are overworked, or 'lazy', or there isn't enough time / budget.

The problem is real because being a good programmer has little to do with being a good communicator or especially a teacher. Most programmers usually view programming as primary, and minimize documentation, tailoring it for their peers. This base is ill-suited for teaching or creating tutorials.

One only needs to look at the last 100 years of chess books to notice that those best at DOING things are hardly capable of EXPLAINING them. Chess books are the laughingstock of the publishing industry, a running joke. Only famous players (winners) get contracts to write chess books (cause that's what fools will buy), whereas even the best trainers have a tough time selling books (unless they self-publish and run a website too!)

Computer books WOULD be the laughingstock of the publishing industry, but audiences prefer intentional comedy, and buyers are too desperate to care.

The traditional publishing industry can only watch with horror and amazement as an out-of-control market drives the worst book fiasco since the Hitler diaries. It parallels the $200 million profit drained out of the public through credit-card fraud from 'secure' PORN sites claiming they need proof of age. Many victims are too panicked to admit they gave out their card numbers and fail to report being robbed.

Computer books are just a variation on a theme, but are probably responsible for more clear-cut forest in Canada than any other single factor, and have helped cause one of the worst ecological disasters to hit North America.

So I guess it doesn't really matter whether programmers can write *good* books if they are helping to strip-mine the earth so that all the top-soil can blow away.

Just a happy thought for you...

Very true. Obviously, it's possible to become a successful programmer without gaining comparable ability in human communication. I suspect that many who excel at human communication (counselors, salespeople, teachers) would have a hard time learning how to talk to a computer. I'm lucky that my speaking and writing abilities have developed alongside my programming abilities, rather than one at the expense of the other. People like me, in some cases, should be the middle-man between programmer and user; I can generally comprehend what the programmer writes, and can express that in terms that a reasonably smart user can understand.

Boy, I don't doubt it. Not only computer books, but technology and business self-help books in general. I think the "...for Dummies" and "Idiot's guide" series are among the most ridiculous. I find it amazing that so many bookbuyers would insult themselves by buying them. But probably worse are the voluminous bibles, by ten different publishing companies, on every major software application and programming language, through each different version. (I often wonder if this effect is to blame for the fact that my college textbooks were almost always obsolete and un-resellable after one semester.) I see it as a tangible representation of the tremendous amount of wasted effort involved in developing proprietary software. Most of the good open-source documentation is spread freely on the internet, since we all know there's not much point to buying a printed manual that will only be outdated next time we run "emerge update world" or equivalent.

I think open-source documentation on the whole is getting better. Wikis have helped, in part, since they at least give the users an easy opportunity to update the documentation if the developers don't feel like doing it. I'm sure many smart people are working hard to improve open-source documentation as we speak, but there are a lot of projects that unfortunately don't take it seriously enough.

To end things on a good note, although the 'no paper needed' revolution via computers never really happened as promised, at least the internet poses the possibility of causing a slowdown in the out-of-control paper consumption problem.

If in particular, information is both free and in a 'paperless' form until and unless needed, perhaps people will only print what they 'need' to print, especially if they are paying on a 'per page' basis.

Maybe home computers couldn't save the forests, but who knows? The internet might just do it.

At least paper is 'recyclable' to a point, and rather efficiently. (I don't want to think about the bleach pouring into our drinking supply, and the poisonous inks being blended back into the environment...)

Thinking about this a little, surely, whilst we i.e. the linux/OSS world, are "enlightened", I'd suggest that the transition to the much vaunted "paperless revolution" might have as much to do with our (all the "advanced" westernised nations) law makers, as it is the fault(?) of the developers of alternative solutions.

If you look at so many laws, they require the retention of records for XXX number of years. At the same time, little seems to have been done toward standardisation of any particular binary/digital format. Here in the UK, it seems that lots of stuff has graduated toward .pdf, which, it would appear, is more to do with cross system compatibility, than it being an efficient format. It also seems to be beneficial, because of .pdf's ability of simulate the paper documents that we're all so familiar with.

Obviously, I can't say for other nations, as I'm unfamiliar with their systems for such things, but here in the UK, there are some laws that require records/documentation to be retained for 100 years - for a standard to last that long, there is a mega need for standardisation, so given that theres so much documentation generated, it'd need to be a pretty compact, efficient format that is also a relatively "low cost" option.

It would also be fair to say, that because of the size of the market, and the proportionally large influence, it's likely that that sort of solution would originate in the US (but you never know)!

My

regards

John

bigjohn, did you figure out the opera issue? Maybe unmasking opera in portage will solve it?

# echo 'net-www/opera ~x86' >> /etc/portage/package.keywords
# emerge -p opera

???

Make sure you have the package.keywords file and if you don't create it. Also, double check that opera is in net-www because I'm not at my Gentoo machine right now.

Yeah, I had to put an entry into packages.unmask as well as the packages.keywords and also I had to make sure exactly what the correct wording was.

At the moment the entry that I succeeded with looks like this

as you can see, I've also had to get masked nvidia driver etc, because one of my upgrades was to the 2.6.11-r4 kernel version which didn't seem to like the earlier driver version.

Ha, I also notice that now there's a beta_3 version of opera 8, but I don't know if it's got to the portage tree yet, as to how I'd get it, well that's gonna be a whole new can of worms!

regards

John