Re: [mv] Reading documentation....

[Birgitt Funk <birgitt@minivend.com>]

On Thu, 23 Sep 1999, Ed LaFrance wrote:

> ******    message to minivend-users from Ed LaFrance <edlafrance@printexusa.com>     ******
> 
> >******    message to minivend-users from mikeh@minivend.com     ******
> >
> >Dear All,
> >
> >I have heard the MiniVend documentation described with adjectives
> >ranging from "awful" to "great". I am doing a lot of documentation
> >for MiniVend 4, keeping some things, removing lots of things, rewriting
> >things, and adding new stuff. But sometimes that is hard work, so I
> >need a place to vent.
> >
> >I will let everyone in on a secret; I am not a programmer. At least
> >I wasn't when MiniVend started. Those hardy few of you who have used
> >MiniVend since 1996 or so will know this if you have read the code. There
> >is much code in MiniVend 3 which is downright amateurish. The code that
> >is new within the last couple of years is at a fairly high and professional
> >level; or so I am told by people I respect.
> >
> >The tool I use most often is Perl. The tool I use second most often is
> >MiniVend.
> >
> >Would it surprise anyone to know that I re-read the Perl FAQ and documentation
> >on a regular basis? Probably not, though I think that perhaps it is not widely
> >done.
> >
> >But does it surprise anyone that I re-read the docs I have written? Not
> >maybe as often as I refer to the source, but I do it all the time. I
> >have to.  Though I have a very good memory, there is absolutely no way
> >I could retain everything about MV. But there is another, perhaps more
> >important reason.  I have learned a lot with experience and my perspective
> >has changed, and things I thought were obvious some time back don't look
> >quite as obvious now. And I think of better ways of doing them. As it
> >is with *any* complex system that I have used over time.
> >
> >So I encourage anyone using any complex language or system, be it Perl,
> >Apache, MiniVend, MySQL, or whatever, to periodically re-read the
> >documentation.
> >You may be amazed at what you learn in light of your hard-won experience.
> >
> >Best,
> >--
> >Mike Heins                          http://www.minivend.com/  ___
> 
> Well said!  There is no substitute for feeding your brain!
> 
> By the way, Mike, what altrustic passion has possessed you and driven you
> to keep developing this system and giving it away?  

I once decided to try writing my own documentation like "Woman's online 
MV-Catalogserver for pastry and other sweet things" and
starting with an outline my first paragraph headline was something like:

	Who has written MiniVend and why ?
                                     ^^^ 
While I learned from 1996 til now that reading the documentation is
something non-enforcable, but endlessly necessary, I also learned that
most probably the only (my, what a liar I am) question (ONE DAY) I will
not be able to answer in my documentation is WHY it was written. All the
other (couple of thousands) questions of technical nature are really a
"piece of cake" against that one. 8-)

Now for this particular question, is it like not finding a simple
answer to a complex question or like not finding a complex answer to a
simple question ?

Who knows... 
Birgitt Funk