[ic] Pee-Poor Documentation Rant

[Mike Heins]

Quoting Mike Tipton (Mike.Tipton@uavco.com):
> Our company is in the process of setting up the IC system. We are
> going though the learning curve like everyone else out there, and
> looking through these endless lists of questions.
>
> With this in mind, >>IF<< someone out there does write some
> documentation for the user (i.e. a step-by-step how-to manual, or just
> some comments on how to use a particular command) how about Red Hat
> setting up a space on their server for "Documentation"?
>

I have asked this question repeatedly, and not received an answer
that I think is reasonable.

Will someone please point me to a set of docs for a application program
*nearly as complex* that we should emulate? I have heard PHP, but PHP is
not an application, it is a language.

I have recently been working with some other programs, open-source
accounting ones, which have documentation not nearly enlightening as
the IC documentation. They are difficult to setup, and you have to
tour the source code to get *any* idea of how to customize them. Once
I got in the code, I found that they didn't even begin to live up to
the standards we have set -- for instance, "use strict" is not in
force.

There is no good answer for all of this that I know of. The only things
I can see that is really going to help the our user base:

1. Improvement of the existing icfoundation document would help
   the user as opposed to the programmer.

2. A theoretical "icprogramming" document would help the programmer
   as opposed to the user.

3. Continuing enhancement of Sonny Cook's excellent tutorial.

Beyond that, we have done a fairly good job (I think) of allowing people
to install and use the program initially with a minimum of fuss.

Once again, if anyone can point to an application we should emulate,
one that installs as easily and has better documentation, I would be
very happy to see that example. Again, I am looking for an application,
not a blank page like PHP, Perl, or Apache.

Regards,
Mike
-- 
Mike Heins
Perusion -- Expert Interchange Consulting    http://www.perusion.com/
phone +1.513.523.7621      <mike@perusion.com>

If you like what you're gettin', keep doin' what you're doin'. -- Hector