[ic] Pee-Poor Documentation Rant

[John Beima]

Talk about foot in mouth Jim...

What you just quoted WAS written by Mike Heinz...

Actually RedHat has done little more than re-arrange Mike's original doc's.
Allowing some of it to be viewed from different angles...

I'll tell you I >HATE< several of the people with Akopia... But THEY are the
problems... Not RedHat...

The docs you are complaining about were what Mike wrote over 2 years ago... As a
matter of fact I started with basicly the same documentation when I first
started with MiniVend 3.0....

>From version 3.0 on, I would hazard to say less than 50 pages has been added to
the docs. I even herd 2 of the 4 books are just the pdfs printed and bound...

John Beima


Quoting Jim Balcom <jim@idk-enterprises.com>:

> Another rant about the woeful documentation:::
> 
> I wanted to set up a Quote Of The Day (QOTD) on my main page using a
> file
> that cron generates from 'fortune'.
> 
> I checked section 2.39 of the 'Interchange Tags Reference' and I came
> away
> wondering what they said. This is VERY ambiguous and unhelpful
> documentation. (It also refers to 'file' which is equally ambiguous.)
> 
> I would like to point out that this whole Interchange Tags Reference
> reminds
> me of a DOS- based program that I had about 10 years ago. It consisted
> of 5
> files and the program would act about like a Chinese Restaurant menu and
> take one phrase from each column at random and make what was supposed to
> be
> technically sound advice, which was actually nothing more than random
> gibberish.
> 
> -----------------------------
> 
> Get this crap:
> 
> 2.39. include
> 2.39.1 Summary
> 
> Parameters: file locale
> Positional parameters in same order
> Pass attribute hash as last to subroutine: no
> Must pass named parameter interpolate=1 to cause interpolation
> Invalidates cache: no
> Called Routine:
> ASP-like Perl call:
> Not applicable
> 
> 2.39.2 Description
> 
> Same as [file name] except interpolates for all interchange tags and
> variables. Does NOT do locale translations.
> 
> ---------------------
> 
> Does anyone know what this said????
> 
> I passed a parameter to interpolation last Wednesday and I didn't get
> off
> the toilet until Friday!
> 
> They set the random number generators and selected phrases from each of
> 5
> columns and put all of this gibberish together in the guise of
> documentation.
> 
> As far as I am concerned this whole documentation is nothing more than a
> pallitive on the part of Red Hat to say that they have provided
> documentation for the product.
> 
> I am deeply sorry that Mike Heins had to sell out to Red Hat. The
> support
> was far better when Mike had some control.
> 
> I can tell you, that after some experimentation I found that I can use
> the
> phrase:
> 
> [include file="pages/qotd"]
> 
> and the contents of that file are displayed on my web page.
> 
> Now, why couldn't something like that have been put in the 'official'
> documentation? It's really a very simple thing. Instead we have to deal
> with
> major obfuscation!
> 
> -= Jim =-
> 
> ----------------------------------------------------------------
> Jim's Linux-Operated Underground Bomb Shelter
> 
> Tagline for Sunday, January 13, 2002 at 22:15 PM:
> To get the point, rub a porcupine backwards.
> 
> ----------------------------------------------------------------
> This Linux System has been up 313 hours
> 
> My web page: http://www.idk-enterprises.com
> ----------------------------------------------------------------
> 
> _______________________________________________
> interchange-users mailing list
> interchange-users@interchange.redhat.com
> http://interchange.redhat.com/mailman/listinfo/interchange-users
> 



John Beima
jbeima@palb.com, support@alocalagent.com, and support@alocalchurch.com

P.A.L.B. Systems - Phone: (780)451-1086 - Fax: (780)447-4760
11639-122 Street, Edmonton, Alberta, Canada, T5M 0B6

Affordable Web Pages - Phone: (888)932-9990 - Fax: (256)351-7297
2713B Spring Place SW, Decatur, Alabama, United States, 35603