[ic] Pee-Poor Documentation Rant

[Rick Dickulous]

I agree completely. IC needs a task based user guide connected to a complete reference. You should be able to look up what you want to do as well as what parts will do it. And an architectural overview too!

On Sun, 13 January 2002, JOHN WRONG wrote:

> 
> 
> 
> damn!! i am 1000000000000000000000000% agree you with that.
> Someone , like us, with the know-how should fix the doc!
> 
> 
> 
> ________________________________________________
> Get your own "800" number
> Voicemail, fax, email, and a lot more
> http://www.ureach.com/reg/tag
> 
> 
> ---- On Sun, 13 Jan 2002, Jim Balcom (jim@idk-enterprises.com) 
> wrote:
> 
> > 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
> > 
> > 
> 
> _______________________________________________
> interchange-users mailing list
> interchange-users@interchange.redhat.com
> http://interchange.redhat.com/mailman/listinfo/interchange-users

Find the best deals on the web at AltaVista Shopping!
http://www.shopping.altavista.com