[ic] 4.7.x RPM? - Interchange Documentation project

IC-Admin interchange-users@lists.akopia.com
Thu Jul 19 16:18:00 2001


On Thu, 19 Jul 2001, Allen Armstrong wrote:

> > -----Original Message-----
> > From: interchange-users-admin@developer.akopia.com
> > [mailto:interchange-users-admin@developer.akopia.com]On Behalf Of Mike
> > Heins
> > Sent: July 18, 2001 11:21 AM
> > To: interchange-users@developer.akopia.com
> > Subject: Re: [ic] 4.7.x RPM?
> 
> <snip>
> 
> > As the person who has written much of the documentation, I am a bit
> > disappointed that I haven't been able to produce what people need.
> > No one has seemed to have been able to produce pertinent examples of
> > what actually *is* needed, which hamstrings me a bit. Most features
> > of Interchange are documented, some of them in excruciating detail.
> > In a lot of cases, people ask questions which would be easily solved
> > by finding appropriate documentation references.
> >
> 
> Hi,
> 
> Perhaps a different approach is needed an Open Interchange Documentation
> project?  Its often very hard for someone very close to the product to write
> documentation because they know the code.  Perhaps like the current
> documentation site the project uses interchange and has different levels of
> contributors.
> 
> Anyways a thought.
> 
> 
> Allen Armstrong
> Member of #interchange on irc.eprofitdesigns.com:6667 (us)
> More information/web irc client check out http://irc.cursor.uk.net/
> 

I am confused. Who has written that he is disappointed he didn't
produce what people need with regards to documentation ?

I disagree. I started to read the new documentation which came with
the 4.7.6 beta release and it's very, very encouraging. With regards to
what actually *is* needed for a so called "Dummy's Guide", you need a
dummy to write this guide to find out what is needed, and dummies
usually don't try it out or give up prematurely. To tell you how
good the current documentation is, I can just say, it's so encouraging
that a dummy like me (who suffered of MiniVend-phobia for a long time)
will try it out again.

Nope. The documentation is so much clearer and so much better organized
than in the very old days. It seems to me that all of that was caused just
by the rapid development and growth of MiniVend and later Interchange with
a lot of changes and either just Mike alone or later few people to
work on both, development and documentation. In the old days it was hard
to follow what happened. Today you can *exactly* see how, where and why
the code is changed and it's even accessible via the web. I think it's
simply a great achievement. 

The only thing difficult about IC is to know what you need to know in
order to understand how IC works. IC is just what we in Germany would
describe as "Stille Wasser sind tief". Unfortunately I don't know how
to express this in English. Or is there something like "Silent waters
are deep" in English ?

Anyhow, the Dummy's Guides are always written as the very last things 
which get published. It's a sign that an application has made it to the
masses of dummies. I'll bet you one day we will have a Dummy's Guide, but
that's the last priority of all documentation papers which might ever be
written. One should never write a Dummy's Guide before the detailed
Reference Guide is not finished (and with all the growth in development
that's almost never done), otherwise your Dummy's Guide is a real dumb
guide and we don't want that.

Let's just be happy because the documentation catches up with the
development changes and that's already fantastic.

Cheers,
Birgitt