[ic] Pee-Poor Documentation Rant

[interchange-users@interchange.redhat.com (Dan Browning)]

[Jim rants about why the docs suck]



> -----Original Message-----
> From: interchange-users-admin@interchange.redhat.com 
> [mailto:interchange-users-admin@interchange.redhat.com] On 
> Behalf Of Jim Balcom
> Sent: Sunday, January 13, 2002 7:48 PM
> To: interchange-users@interchange.redhat.com
> Subject: [ic] Pee-Poor Documentation Rant
> 
> 
> 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
>