[ic] Pee-Poor Documentation Rant

Garry interchange-users@interchange.redhat.com
Tue Jan 15 08:47:01 2002


I am afraid I have to agree with Jim.

After several months of trying to figure out IC (which I am sure is a great
piece of software) I finally defected to OSCommerce - which I had up and
running in less than a day, and I was able to fully understand.

cheers all

Garry

----- Original Message -----
From: "Jim Balcom" <jim@idk-enterprises.com>
To: <interchange-users@interchange.redhat.com>
Sent: Tuesday, January 15, 2002 1:45 AM
Subject: RE: [ic] Pee-Poor Documentation Rant


> On Sun, 13 Jan 2002, Jeff Carnahan wrote:
>
> JC>>Visiting the IC homepage, I entered "include contents of a file" into
the
> JC>>search box.
> JC>>
> JC>>I was given a listing of pages that might help me, including one
titled
> JC>>"FILE and INCLUDE".
> JC>>
> JC>>Clicking on it, I see the handy description of what these tags do:
> JC>>
> JC>>"FILE and INCLUDE -- These elements read a file from the disk and
insert the
> JC>>contents in the location of the tag."
> JC>>
> JC>>Thus, with two clicks I've found exactly what solves this problem. The
> JC>>documentation for the [file] tag is very helpful, it even elaborates
on
> JC>>security risks that (being a good sys admin) I should be aware of.
> JC>>
> JC>>The documentation for [include] is also very helpful. "Same as [file
name]
> JC>>except interpolates for all Interchange tags and variables." Shall I
> JC>>deconstruct that? "Same as [file name]" .. Great, so it includes a
file for
> JC>>me. Cool.  "except interpolates for all Interchange tags and
variables." ..
> JC>>Even better, if the file I include into the page has a [page
> JC>>href="sku_here"]...[/page] tag (or any other Interchange tag or
variable) it
> JC>>will be interpolated. Awesome. Now I can easily save commonly used
site
> JC>>navigation, design and thematic elements into single files (even if
they
> JC>>have IC stuff in them).
> JC>>
> JC>>Really, I fail to see the difficulty here finding exactly what you
wanted to
> JC>>know.
>
> The difficulty?
>
> Here's the difficulty.....
>
> We download the software. The documentation tells us little. We are told
to
> RTFM. "What FM?" we ask. We are told to go and download the documentation.
> We do that. We print out the FM that we download, and we get it neatly
bound
> - all FIVE parts, and I have them here for ready reference.
>
> The difficulty is that apparently this FM that I spent money to print out,
> laminate the covers and to bind is not a 'Fine Manual' but an 'Un-Fine
> Manual' because I am supposed to go to Red Hat's web page (where I can
never
> find a damned thing! [I've written about that farce before!]) and dig some
> more.
>
> Here's another difficulty that I laid out in my original message (did you
> read it all?)
>
> JC>>The documentation for [include] is also very helpful. "Same as [file
name]
> JC>>except interpolates for all Interchange tags and variables." Shall I
> JC>>deconstruct that? "Same as [file name]"
>
> I'm glad that you think that is helpful! It reads like something that
> trained apes have put together from a random assortment of words. If you
can
> understand that gibberish, then I'm happy for you!
>
> And, in none of that did you show how to call it and make it work! And,
that
> important bit of information is not in any of the manuals that I have, nor
> in what you have posted.
>
> And, another thing, I know for a fact that quite a few people on this list
> are not on-line all of the time, and some are paying by the minute for
> connect time. So, why force them to go to a web page for research when
they
> should be able to find it all in the dosnloaded documents?
>
> -= Jim =-
>
> ----------------------------------------------------------------
> Jim's Linux-Operated Underground Bomb Shelter
>
> Tagline for Monday, January 14, 2002 at 20:30 PM:
> I parked my hard disk and now I can't find it!
>
> ----------------------------------------------------------------
> This Linux System has been up 335 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


_________________________________________________________
Do You Yahoo!?
Get your free @yahoo.com address at http://mail.yahoo.com