[ic] Taking a Poll

Doug Alcorn doug@lathi.net
16 Apr 2001 15:59:15 -0400

IC-Admin <interchange@my-school.com> writes:

> For those people neither the many example catalogs, nor the dense
> documentation should be a hurdle.

I'm surprised how many people have said the IC documentation is
dense.  I would define "dense" as "a lot of information on not much
volume" or maybe "more information than expected for the volume".  I
don't think the IC documentation (at least for 4.6.x) qualifies.

A little bit of background: I'm a degreed engineer (only relevant in
that I'm used to reading complex documentation) and have been a
professional programmer for six years.  Granted, I have less than one
year with IC.  I have been doing perl programming for four years.  I
have nearly 10 years experience with Unix.

That said, I usually strike out when turning to the documentation.
Yes, it does give the perl syntax for calling the function.  Sometimes
it gives the syntax for the IML way of calling it.  However, what
lacks is either a description or purpose of the function or a
description of the parameters.  Here's a good example of what I'm
talking about:

,----[ http://developer.akopia.com/cgi-bin/ic/dev/ictags_25.html ]
| 2.22. ecml
|      Parameters: name function 
|      Positional parameters in same order. 
|      The attribute hash reference is passed to the subroutine after the parameters
|      as the last argument. This may mean that there are parameters not shown
|      here. 
|      Must pass named parameter interpolate=1 to cause interpolation. 
|      Invalidates cache: no 
|      Called Routine: 
|      ASP/perl tag calls:
|        $Tag->ecml(
|            {
|             name => VALUE,
|             function => VALUE,
|            }
|        )
|      OR
|        $Tag->ecml($name, $function, $ATTRHASH);

There's only three pieces of information here: a function is named
"ecml" and it has two parameters "name", "function".  All the rest of
this "documentation" is standard template stuff.  That's not very
dense at all.

I'm not really picking on the "ecml" function.  I know that there is
some documentation embedded in the lib/Vend/EMCL.pm file that isn't
reflected on the developer.akopia.com site.  The point is that there
are many other functions with this _exact_ same documentation with the
above mentioned three pieces of information changed.

What can be done in the immediate time-frame?  Add a link to each of
the tags that says what file they are implemented in.  Add some
documentation that tries to explain the directory hierarchy in 'lib'.
Write a brief package "foo" is responsible for "bar".  Write a brief
"Here's what happens when a page is submitted to the interchange
daemon."  These are things I think experienced developers would like
to know when they are new to interchange.
 (__) Doug Alcorn (mailto:doug@lathi.net http://www.lathi.net)
 oo / PGP 02B3 1E26 BCF2 9AAF 93F1  61D7 450C B264 3E63 D543
 |_/  If you're a capitalist and you have the best goods and they're
      free, you don't have to proselytize, you just have to wait.