[ic] Beima's Response!

[Dan B]

What is this list for?

Community.

In my opinion, that little word can mean a lot.  For those of you that feel 
annoyed by the sheer volume of newbies asking the same question over and 
over again, or one that is answered in the docs:  would you prefer it if 
you were the only user on the list?  Or only 10?  20?  Interchange has at 
least tens of thousands of users.  We are bound to get all kinds of dumb 
questions (I'm renowned for asking them).

But there is so much value in all of those users, that to me it is worth it 
to answer their questions and try to help them get through the 
documentation.  I find a lot of value in Interchange comes from the 
community.  And community starts with newbies.  You never know when a 
newbie that doesn't understand the documentation will become the next 
Stefan Hornburg, or contributes a new usertag for a financial service, or a 
patch that allows application-level database clustering, for example (I'm 
working on it ;^).

I think that too many are applying the stereotype of "too lazy to read the 
documentation" when really it's, "too hard to _understand_ the 
documentation".  In fact, when I started, it was hard to know HOW to search 
the documentation/mailing list.  I didn't know about "grep -r", and the 
google search.  I was hungry, but didn't know how to fish.

That is why, now, I *try* to answer every question I can, even though I'm 
usually not very good :-).  Because I'm trying to build the 
community.  Frankly, I do it because I'm selfish.  Because I receive a lot 
of value when the community is strong; the environmental diversity 
increases Interchange's technical value much more, more diverse ideas are 
shared, etc.  To me, it is the equivalent of sitting in an office at Oracle 
doing development on 10i.  We are the ones who can download the CVS and 
contribute straight back into the source.  So I'm going to do what I can to 
help the new intern, even if "what I can" isn't much.

I think that Red Hat (Akopia) realizes that there is value in demo-specific 
documentation (the "engine manual") in addition to the general interchange 
documentation (the "combustion theory").  For example, Jon Jenson mentioned:
http://lists.akopia.com/pipermail/interchange-users/2001-February/004991.html
--------------------------------------------------------------------------------
On Thu, 22 Feb 2001, Bob Puff@NLE wrote:
 > Is there any doc file on the Construct demo itself, telling how /
 > where things are?  There seems to be a ton of stuff in there.

There's plenty of useful stuff throughout the other docs, but nothing
specific on the demo yet. We plan to have separate documentation for the
demo for the 4.8 release. Sorry!
---------------------------------------------------------------------------------
Basically, I think we all have high goals for Interchange.  It's too bad 
that right now we don't have the holy grail of documentation.  But instead 
of spending hours flaming about how many newbies don't read/understand the 
docs (inluding me) and what to do about it, why doesn't someone _do_ 
something about it?

Aren't there some experts out there that can run circles around "construct" 
demo?  What if the said experts took the time to contribute to the 
docs?  E.g., "Gee mike, I got sick of people asking how to send out email 
confirmations, so I wrote down the 1-2-3 and A-B-C baby steps of how it is 
done in Construct".

Unfortunately, most people don't spontaneously write metric tons of 
documentation.  But there are so many unique individuals on this list that 
I would wouldn't put it past the community.

My hope in writing to you all is that we can get back to encouraging and 
helping, rather than tearing down.  Give a man a fish and he will eat for a 
day.  Teach a man to fish and he will eat for a lifetime.  Are we teaching 
newbies how to find out what they want to find out?  "grep -r" and the 
mailing list URL's are posted often, that is examples of teaching to 
fish.  So is giving a URL to the location in the docs, or to a given mail 
archive.  In fact, even mentioning "search for terms XYZ and ABC" is still 
"teaching to fish".

And by the very definition of doing that, we will weed out the lazy ones 
who don't want to learn it (i.e. just want their fish handout).  And we 
avoid the alternative of earnest users who want to learn to fish but can't 
because no one teaches them.

For each newbie or repeat question, here is what I try to do (often I fail):
         - recommend search terms to use on a search that will result in 
the answer
         - recommend a chapter / section in the docs
         - recommend a resource outside of interchange (unix for dummies, etc.)
         - link to a specific doc section
         - link to post from mailing list archive (very illuminating)
         - explain HOW to search for information (grep -r usage, google)
         - real time documentation (for undocumented, unexplored topics, or 
opportunities to pontificate, like now).

Doing the above takes a *little* more time than "RTFM".  But sometimes 
"RTFM" doesn't equate with the steps above, and the value that the 
community will recieve by attempting to be a little more recieving can be 
unexpectedly large.  CFM and others already do this very well.  In fact, I 
have recommended that the mailing list be setup to reply to every *new* 
user post (i.e. the first post you write, but not thereafter) with a 
message that outlines all the resources for searching for the answer to 
your problem.

In conclusion, I think that if we all have a more helpful attitude, then we 
will add to the ranks of people who use/understand interchange, including 
the amount of people who write patches.  It's too bad that we don't have 
more "core" developers now, but we can all help to get more people to that 
point.  (I, for one, am striving to get there).

Well, now that I have won the "most kilobytes wasted in a single e-mail" 
award, I'm going to retire to my iml programming.  Thanks for listening,

Dan Browning, Cyclone Computer Systems, danb@cyclonecomputers.com