[ic] Pee-Poor Documentation Rant

[interchange-users@icdevgroup.org]

On Thu, Jul 25, 2002 at 01:50:57PM -0400, Mike Heins wrote:
> 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"?
> >
> 

...

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


I don't think the problem is the documentation, but the background that
people bring with them.  It's always easier to blame it on someone else.

Perhaps a listing of background one should have vs what one can do:


Your experience                    What you can do
sysadmin, lots of *NIX and perl    anything you want

... stuff in the middle

what's telnet/ssh                  complain


Even if such a chart were purely anecdotal it would be useful to keep
people from getting in over their heads.  And fun to read too.  :-)

BOFH sez maybe about line 10 of makecat should be:

exit 1; # if you find this, comment it out and proceed.

;^>





-- 

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