[Dirvish] POD, new FAQ, and netiquette

Keith Lofstrom keithl at kl-ic.com
Wed Feb 16 10:55:08 PST 2005


I have converted all the manual pages to POD, Perl's "plain old
documentation".  I also converted the FAQ (Frequently Asked
Questions) to POD, and added a few items, based on recent emails. 

You can find the new FAQ at:

 http://www.dirvish.org/FAQ.html .

Note, translating the POD to HTML with the command  pod2html
yields a FAQ that is servicable but not quite as pretty as the
original FAQ.html from jw .  POD is just not as flexible as HTML. 
However, I prefer the documents usable rather than pretty.

The old FAQ is at 

 http://www.dirvish.org/FAQold.html

... if you want to comb through both for discrepancies.

-----

A note on list etiquette:  From time to time, we will have new
people ask questions of this list that they could find out by
reading the FAQ or the man pages or the Wiki, or scanning the
mailing list with a google to "site:www.dirvish.org  keywords". 
If you feel you must admonish a newbie for laziness, please do
it off the list.  On the list, please give them a pointer to
the appropriate documents, and a terse but useful correct answer
containing the keywords they (and others!) might need for future
searches.

The main reason for this forbearance is to protect the quality of
the email archives.  Someday I hope to add a search feature to
Mailman (there are patches, but they aren't in the main branch
of the software yet) and I don't want people searching the archives
and finding a lot of complaints, rather than useful information. 
That just makes it more likely that they will pester us with silly
questions,  forever.

No question is silly until it has been answered 10 different ways. 
People will use different search strings, learn differently, and
use different words for the same thing.  Most people are willing
to learn, given a little help and respect.  Those that are not
willing to learn, but who have money, are called "customers".

That said, so far you guys have been great!  Keep it up!

Newbies:  Search the FAQ, the man pages, and the Wiki.  Gather
keywords so you can ask intelligent and specific questions, of
the list or of Google.  If your questions are not answered by the
online documents, then a good question can help us improve them.

However, a *bad* question, like "help?", just annoys us.  See
Eric S. Raymond's excellent "How To Ask Questions The Smart Way"
at http://www.catb.org/~esr/faqs/smart-questions.html .

This information is here in case somebody searches for
"dirvish FAQ" or "dirvish questions".  See the logic?

Keith

-- 
Keith Lofstrom          keithl at keithl.com         Voice (503)-520-1993
KLIC --- Keith Lofstrom Integrated Circuits --- "Your Ideas in Silicon"
Design Contracting in Bipolar and CMOS - Analog, Digital, and Scan ICs


More information about the Dirvish mailing list