Fw: [mv] minivend--interchange documentation

["birgitt" <birgitt@cais.com>]

******    message to minivend-users from "birgitt" <birgitt@cais.com>     ******

Hi Christopher, you made it !

> > ******    message to minivend-users from "Greg (Sonny) 
Cook" <sonny@akopia.com>     ******
> > 
> > 

Hi there,  Sonny Cook !

> > Hi all,
> > By way of introduction, I am one of the developers at Akopia.  I have
> > taken on (bravely IMHO) the task of documentation organization for our
> > next release of intervend.
> >  Even though I am personally opposed to  documentation, 
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

That deserves an explanation !!!  8-) 
I think we shouldn't let you off the hook for that one.

> 
> > I have a grand vision for a complete set of documents of
> > the project.  Kind of everything from "What's a computer?"
> 

Please.... .you are a Cook(y), really. What's a Cook(y) ? That
would be worth documenting, may be.. 8-).

> 
> >  to "minichange hacker" level.
> >  There is of course an already extant and rather copious
> >  corpus avaliable from Mike. 
>>   I've noticed it's still pretty hard to get going though.  
> 

How did you notice that ? 8-) 

Who do you think will be the readers  and users of the 
 documentation ? Are you thinking in categories consultants/gurus/cool 
 nerds on the one side and newbies, dummies, mommies, the 
 technologically challenged on the other ? Oh, I can find other, nicer,
politically correct words for the same thing if you like. Do you intend
to write sets of manuals for different knowledge levels ? I  wished
you wouldn't fall into that trap. 
  
 If you are going to write the documentation imagine
an old, ugly, bitter, librarian type of lady looking over your shoulder
with magnifying glasses picking on every inconsistency in logical order of 
 your writings, sending you to the corner for any missing MML tag
not explained. 8-)
 
> > At any rate, rather than share my concerns with the present
> > state of the documentation, I'd like to determine what sort of
> > documentation people would like to see.
> 

Something complete, precise, consistent, clearly written, logically 
ordered. Something terribly boring, utterly lacking any sense of beauty and
humor. 

Imagine YOU would have to buy your docs ! Would it be fast become that indispensible 
reference work spilled over with coffee, sweat and all worn out from hourly 
usage to tackle the next item of your interchange customization ? 

Or would it be this 3 pound heavy weigth paper pack, which is half full 
of screen shots explaining the newbie which  button to click and which option 
to choose from the drop down menu ?
 
Instead of showing several ways of doing something halfway,  show one way 
of doing something all the way through.
 
 Be religiously complete, fanatically updated (build a system where people can
add their own donations to the code or docs ) and be a zealous
missionary in explaining each and every  acronym, any technical verbiage which might be 
hard to  understand for  non-native English users. And if you can't help to make
some jokes in the docs, can you explain the slang words  and idioms to us outsiders,
please ? We want to share the laugh, ok ?

> > Currently I am combing through the mailing list archives, trying to rescue
> > usefull information from the past.  
> > 

Clinton would say "I feel your pain..." 8-)

Is the old documentation mailing list archived  and accessible to you ? 
People have mentioned wishes before..

To stop kidding around  (hope you didn't mind my tone, I needed a break from
RTFM - not Minivend's of course 8-)),  please document the MML tags 
in a consistent and very complete way. I can only support John Beima's comment in that
respect. Perl gurus don't need the docs, they can read the source. But Minivend was
not written for Perl gurus. At least I hope so. It was written for people who can't read Perl 
and are willing to learn the Minivend tags. So, document them clearly. 8-)

Good luck, and take it easy !

Birgitt
P.S. Don't forget, you owe us an explanation why you personally are against documentation.
Otherwise you risk me asking again ! 8-)
 
> > Thanks,
> > Sonny Cook
> > 
> > 
> > -
> > To unsubscribe from the list, DO NOT REPLY to this message.  Instead, send
> > email with 'UNSUBSCRIBE minivend-users' in the body to Majordomo@minivend.com.
> > Archive of past messages: http://www.minivend.com/minivend/minivend-list
> > 
> 

-
To unsubscribe from the list, DO NOT REPLY to this message.  Instead, send
email with 'UNSUBSCRIBE minivend-users' in the body to Majordomo@minivend.com.
Archive of past messages: http://www.minivend.com/minivend/minivend-list