[ic] Beima's Response!
Sun, 01 Apr 2001 22:34:30 -0800
What is this list for?
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:
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
- 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
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, email@example.com