[ic] Pee-Poor Documentation Rant

[Jim Balcom]

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
----------------------------------------------------------------