[Asterisk-Users] FAQ, Documentation, How-to, etc

[Tilghman Lesher]

On Wednesday 19 November 2003 19:35, Rich Adamson wrote:
> What's been suggested for a FAQ and other "much needed information"
> for such a _HIGHLY_ technical software product has been proven
> thousands of times in the past few months. Even an untrained monkey
> can see that, including many geeks. Those that are against it are the
> very _few_ arrogant self-centered egotistical few that think their
> middle initials are VoIP. It would be very easy to publish a list of
> such names on this list and only consume a half-inch of email space
> (even with Outlook Express in bold print, heaven forbid). And, their

Or those who have seen such messages half a day earlier and seven
times in the past week and are getting really tired of answering the
same questions over and over and over.  It's not a problem isolated to
these lists, either, and some very smart people have tried (and failed)
to address these problems in the past with other lists.

> first names do not start with Mark either (Everyone, please note
> Mark's political absence from this somewhat "hot" topic; excellent
> posture.)

Mark's time is extremely valuable to the community, and thus, it seems
he ignores most of the really stupid questions, questions that could be
answered by anybody applying the least bit of effort.  Really, I rarely
use the site:digium.com specifier to searching the asterisk mailing
lists; usually, applying the keyword "asterisk" to the search tends to
net nearly equal results.

> The majority of recent postings to the list are, without a doubt,
> coming from folks that have just recently found an app they believe
> in and would like to try it. But the arrogant _few_ (about 3, if
> someone's counting) consistently discourage these same people with
> "did you search the archives" or "any dumb fxxx" should know that;

If my count is correct, most of these "arrogant" people are contributing
developers.  Insult them, drive them away, and you will have harmed
the community.

> just read the code!!! If I see one more post from those same arrogant
> <people>, I'm tempted to build an army <of you know what> and see how
> well their business and customers stand up to the DS3 <pressure>.

This is neither here nor there, but under the Patriot Act, you have just
committed an act of domestic terrorism.  No, I'm not going to report you
to the FBI, but you should really think about making such threats in the
future.  It is not conducive to settling any differences and is more
likely to widen the apparent rift in the Asterisk community.

<snip>
> A minimum of ten years of Internet history has already proven that
> sharing information is a very positive thing. Yet, on "this" list and
> with this product, the overwhelming objective by those that have a
> clue is to _not_ share the intricacies of how to accomplish basic
> telephony functions. Most of us do understand why a couple of
> cookie-Krums (intended) are scattered around though!!!

Because many of the developers have moved on to introduce
new features into Asterisk and are annoyed by people who cannot
lift a finger to help themselves, but expect to be spoonfed
knowledge.  Yes, the most appropriate response is simply to ignore
them, but sometimes, the question is simply repeated a few days
later, with confusion on the part of the sender why nobody
responded initially to their message.

> There has been several attempts by _many_ to help document the
> product, but even _that_ effort has been consistently undermined by a
> select _few_. Until knowledge and experiences are shared <openly>,
> the product will likely remain in its present state. (Sorry Mark!)

I'm afraid the _official_ documentation effort has been largely a failure:

http://lists.digium.com/pipermail/asterisk-users/2002-December/006700.html (beware wrap)

The Wiki has arisen from a need within the community, it is not restricted
in distribution (although redistributing a Wiki isn't easy anyway), and
judging from its growth in a few short weeks, dwarfing the existing
documentation, it is a great success.

> For those that have actually read this far, please express your
> honest opinion as they're truly are some people lurking that want to
> learn and can impact the negativity that is so common on this list.
>
> For those that are new to the list and don't understand the
> frustration, please disregard.

No, to people new on the list, please do NOT disregard.  Learning to
ask questions intelligently, by showing even a modicum of the attempt
to help yourself is likely to produce far more friendly or, at the very
least, polite responses.  It's unfortunate that this same message can't
be directed to _every_ new person who joins the list, because once
this message goes out to the list, it will remain in the archives, and we
know how often some newbies search the archives.

To be clear, I am not attacking all newbies.  Even a few of the worst
offenders learn from their mistakes and move on to be developers of
new and interesting features.

-Tilghman