Regurgitating the Documentation

My favorite blog posts, forum posts, and web sites are the ones that just regurgitate the documentation for a product. Any moron that gets the product documentation can read it. Sure, I’ll give some people a break if the docs are awful. But, for instance, Oracle has documented the living crap out of installing their products on Linux. Why do people feel the need to type up how to install Oracle products on Linux? Is it just to steal search-engine results away from the company itself?

Installing Oracle 10g on Linux is a great example of this B.S. I know, for a fact, that if you grab the Oracle quick-start guide they tell you exactly how to install their product, step-by-step. Let’s take a quick look at user-supplied documentation and see if people are adding value or stealing search results.

How to Install Oracle 10g on RedHat Enterprise 3 – suggestion: skip the 80% of your documentation that Oracle took care of and just put in the part about setting the environment variables. If you want to be helpful to n00bs you should explain that you need to set ORACLE_BASE to whatever you installed to, not necessarily /u01/app/oracle. They’re going to cut-n-paste your stuff and wonder why it’s not working. The product is also “Red Hat” (two words) “Enterprise Linux 3.” You get a D.

Installing Oracle 10g R1,R2 on RHEL 4, 3, 2.1, etc. is my next target. This guy gets props for calling it RHEL, and for having it updated for recent releases of the software. He restates a ton of what is in the manual already, but he also adds value to some of it. The post-installation tasks and tips & hints sections are useful, but the obviousness of the errors and problems section make me want to take a chainsaw, have someone hold my beer, and say “watch this” as I lop my own head off. I’ll give you a C for your effort.

Next up is the Gentoo Wiki’s HOWTO Install Oracle 10g. The first parts are near-verbatim restatements of the Oracle docs. The end parts and the screen shots are impressive, though, because it gives you what you need to run Oracle 10g on Gentoo. Nevermind that these kind of docs are the bane of support staff everywhere. Gentoo isn’t exactly a supported Linux distribution, so everybody using these docs is 100% off the reservation. Add a statement to that effect at the beginning and all is good. You get a C-, mostly because of the section telling people to steal libaio from SuSE. Way to leech.

ORACLE-BASE – Linux and Oracle just condenses all of the documentation from Oracle down into a page and a half, minus all that neat explanation of why you’re making changes that Oracle supplies. That’s where it isn’t a link farm. Way to steal attention from Oracle, like those jerks that clone Wikipedia to steal their searches. You get an F.

Togaware’s Oracle 10g Release 2 has people going off the reservation by installing on Debian. Hey, cool, but again there is no disclaimer that people are going to be unsupported. Apparently the section on creating an /etc/redhat-release implies that. Most of this is all the standard Oracle docs, but the section on using Oracle 10g and importing data might be useful. The troubleshooting section looks useful. You get a B.

That’s just the first page of the Google results, and the best ones. Looking at page two drains my spirit with spelling errors, reposting the Oracle docs, link farms, and more. People, if you’re going to write your own docs:

• don’t duplicate those that the vendor wrote already.
• maintain the pages, which may involve removing some if the vendor catches up.
• check the spelling on your pages.
• tell people if you are leading them down a path that is unsupported. Just because you can do something doesn’t mean they should. If you’re screwing around you can run Oracle on Gentoo, but it isn’t appropriate for a production database, and 95% of the people reading your docs aren’t going to make that distinction on their own.
• above all, add value. Don’t bother rewriting what has been said already if you aren’t going to add something to it.