[ic] Pee-Poor Documentation Rant

interchange-users@interchange.redhat.com interchange-users@interchange.redhat.com
Mon Jan 14 08:47:00 2002


On Mon, Jan 14, 2002 at 12:30:42AM -0700, John Beima wrote:
...
> 
> You have to remeber the docs are VERY GOOD >IF< and only >IF< you are a very
> fluent Perl programmer. I found the more I understood Perl, the more I
> understood how Mike documentated things...

And there is NO WAY any amount of documentation is going to make you a
good perl programmer.  That is up to **you**, not RH or MH.

I'll also bet, **without looking**, that one could grep examples of 
[file name=] or [include] tags in the standard demos.

Inluding a random qotd is different.  Do you want it autogenerated
with each page view, or really is it daily, meaning you also need
to understand outside processes and permissions?  The docs will
not cover how to run your system, either.  Nor should they.


> 
> 
> John Beima
> 
> 
> Quoting JOHN WRONG <java02@ureach.com>:
> 
> > 
> > 
> > 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
> > 
> 
> 
> 
> 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
> _______________________________________________
> interchange-users mailing list
> interchange-users@interchange.redhat.com
> http://interchange.redhat.com/mailman/listinfo/interchange-users

-- 

Christopher F. Miller, Publisher                               cfm@maine.com
MaineStreet Communications, Inc           208 Portland Road, Gray, ME  04039
1.207.657.5078                                         http://www.maine.com/
Content/site management, online commerce, internet integration, Debian linux