[ic] Pee-Poor Documentation Rant

Prasit P interchange-users@interchange.redhat.com
Mon Jan 14 09:29:01 2002


If RedHat wants this e-commerce application to be widely
used for Linux, it should rewrite the document.  Its
document is just like easily take out comments from perl
scripts and put it together without source code, like the
blind watching a movie.

Even you are Perl knowledgeable, you won't be able to
figure out easily what the document is trying (or not) to
tell you.

I personally like this application, but the deep learning
curve here pull me back a little bit.  I'm sure it kicks a
huge bunch of others out too.  

I believe RH knows what the result of good software with
poor documentation is.  

Prasit



--- cfm@maine.com wrote:
> 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
> _______________________________________________
> interchange-users mailing list
> interchange-users@interchange.redhat.com
>
http://interchange.redhat.com/mailman/listinfo/interchange-users


=====
GROWTH - The rung of a ladder was never meant to rest upon, 
but only to hold your foot long enough to put the
other foot higher.

-anonymous

__________________________________________________
Do You Yahoo!?
Send FREE video emails in Yahoo! Mail!
http://promo.yahoo.com/videomail/