Posting Guidelines for comp.lang.perl.misc ($Revision: 1.7 $)

This newsgroup, commonly called clpmisc, is a technical newsgroup intended to be used for discussion of Perl related issues (except job postings), whether it be comments or questions.

As you would expect, clpmisc discussions are usually very technical in nature and there are conventions for conduct in technical newsgroups going somewhat beyond those in non-technical newsgroups.

The article at:

    http://www.catb.org/~esr/faqs/smart-questions.html

describes how to get answers from technical people in general.

This article describes things that you should, and should not, do to increase your chances of getting an answer to your Perl question. It is available in POD, HTML and plain text formats at:

 http://www.augustmail.com/~tadmc/clpmisc.shtml

For more information about netiquette in general, see the ``Netiquette Guidelines'' at:

 http://andrew2.andrew.cmu.edu/rfc/rfc1855.html

A note to newsgroup ``regulars'':

   Do not use these guidelines as a "license to flame" or other
   meanness. It is possible that a poster is unaware of things
   discussed here.  Give them the benefit of the doubt, and just
   help them learn how to post, rather than assume that they do 
   know and are being the "bad kind" of Lazy.

A note about technical terms used here:

   In this document, we use words like "must" and "should" as
   they're used in technical conversation (such as you will
   encounter in this newsgroup). When we say that you *must* do
   something, we mean that if you don't do that something, then
   it's unlikely that you will benefit much from this group.
   We're not bossing you around; we're making the point without
   lots of words.

Do NOT send email to the maintainer of these guidelines. It will be discarded unread. The guidelines belong to the newsgroup so all discussion should appear in the newsgroup. I am just the secretary that writes down the consensus of the group.

Before posting to comp.lang.perl.misc

Must

This section describes things that you must do before posting to clpmisc, in order to maximize your chances of getting meaningful replies to your inquiry and to avoid getting flamed for being lazy and trying to have others do your work.

The perl distribution includes documentation that is copied to your hard drive when you install perl. Also installed is a program for looking things up in that (and other) documentation named 'perldoc'.

You should either find out where the docs got installed on your system, or use perldoc to find them for you. Type perldoc perldoc to learn how to use perldoc itself. Type perldoc perl to start reading Perl's standard documentation.

Check the Perl Frequently Asked Questions (FAQ)
Checking the FAQ before posting is required in Big 8 newsgroups in general, there is nothing clpmisc-specific about this requirement. You are expected to do this in nearly all newsgroups.

You can use the ``-q'' switch with perldoc to do a word search of the questions in the Perl FAQs.

Check the other standard Perl docs (*.pod)
The perl distribution comes with much more documentation than is available for most other newsgroups, so in clpmisc you should also see if you can find an answer in the other (non-FAQ) standard docs before posting.

It is not required, or even expected, that you actually read all of Perl's standard docs, only that you spend a few minutes searching them before posting.

Try doing a word-search in the standard docs for some words/phrases taken from your problem statement or from your very carefully worded Subject: header.

Really Really Should

This section describes things that you really should do before posting to clpmisc.

Lurk for a while before posting
This is very important and expected in all newsgroups. Lurking means to monitor a newsgroup for a period to become familiar with local customs. Each newsgroup has specific customs and rituals. Knowing these before you participate will help avoid embarrassing social situations. Consider yourself to be a foreigner at first!

Search a Usenet archive
There are tens of thousands of Perl programmers. It is very likely that your question has already been asked (and answered). See if you can find where it has already been answered.

One such searchable archive is:

 http://groups.google.com/advanced_group_search

If You Like

This section describes things that you can do before posting to clpmisc.

Check Other Resources
You may want to check in books or on web sites to see if you can find the answer to your question.

But you need to consider the source of such information: there are a lot of very poor Perl books and web sites, and several good ones too, of course.

Posting to comp.lang.perl.misc

There can be 200 messages in clpmisc in a single day. Nobody is going to read every article. They must decide somehow which articles they are going to read, and which they will skip.

Your post is in competition with 199 other posts. You need to ``win'' before a person who can help you will even read your question.

These sections describe how you can help keep your article from being one of the ``skipped'' ones.

Is there a better place to ask your question?

Question should be about Perl, not about the application area
It can be difficult to separate out where your problem really is, but you should make a conscious effort to post to the most applicable newsgroup. That is, after all, where you are the most likely to find the people who know how to answer your question.

Being able to ``partition'' a problem is an essential skill for effectively troubleshooting programming problems. If you don't get that right, you end up looking for answers in the wrong places.

It should be understood that you may not know that the root of your problem is not Perl-related (the two most frequent ones are CGI and Operating System related), so off-topic postings will happen from time to time. Be gracious when someone helps you find a better place to ask your question by pointing you to a more applicable newsgroup.

How to participate (post) in the clpmisc community

Carefully choose the contents of your Subject header
You have 40 precious characters of Subject to win out and be one of the posts that gets read. Don't waste them. Take care while composing them, they are the key that opens the door to getting an answer.

Spend them indicating what aspect of Perl others will find if they should decide to read your article.

Do not spend them indicating ``experience level'' (guru, newbie...).

Do not spend them pleading (please read, urgent, help!...).

Do not spend them on non-Subjects (Perl question, one-word Subject...)

For more information on choosing a Subject see ``Choosing Good Subject Lines'':

 http://www.cpan.org/authors/id/D/DM/DMR/subjects.post

Part of the beauty of newsgroup dynamics, is that you can contribute to the community with your very first post! If your choice of Subject leads a fellow Perler to find the thread you are starting, then even asking a question helps us all.

Use an effective followup style
When composing a followup, quote only enough text to establish the context for the comments that you will add. Always indicate who wrote the quoted material. Never quote an entire article. Never quote a .signature (unless that is what you are commenting on).

Intersperse your comments following each section of quoted text to which they relate. Unappreciated followup styles are referred to as ``top-posting'', ``Jeopardy'' (because the answer comes before the question), or ``TOFU'' (Text Over, Fullquote Under).

Reversing the chronology of the dialog makes it much harder to understand (some folks won't even read it if written in that style). For more information on quoting style, see:

 http://web.presby.edu/~nnqadmin/nnq/nquote.html

Speak Perl rather than English, when possible
Perl is much more precise than natural language. Saying it in Perl instead will avoid misunderstanding your question or problem.

Do not say: I have variable with ``foo\tbar'' in it.

Instead say: I have $var = ``foo\tbar'', or I have $var = 'foo\tbar', or I have $var = <DATA> (and show the data line).

Ask perl to help you
You can ask perl itself to help you find common programming mistakes by doing two things: enable warnings (perldoc warnings) and enable ``strict''ures (perldoc strict).

You should not bother the hundreds/thousands of readers of the newsgroup without first seeing if a machine can help you find your problem. It is demeaning to be asked to do the work of a machine. It will annoy the readers of your article.

You can look up any of the messages that perl might issue to find out what the message means and how to resolve the potential mistake (perldoc perldiag). If you would like perl to look them up for you, you can put ``use diagnostics;'' near the top of your program.

Do not re-type Perl code
Use copy/paste or your editor's ``import'' function rather than attempting to type in your code. If you make a typo you will get followups about your typos instead of about the question you are trying to get answered.

Provide enough information
If you do the things in this item, you will have an Extremely Good chance of getting people to try and help you with your problem! These features are a really big bonus toward your question winning out over all of the other posts that you are competing with.

First make a short (less than 20-30 lines) and complete program that illustrates the problem you are having. People should be able to run your program by copy/pasting the code from your article. (You will find that doing this step very often reveals your problem directly. Leading to an answer much more quickly and reliably than posting to Usenet.)

Describe precisely the input to your program. Also provide example input data for your program. If you need to show file input, use the __DATA__ token (perldata.pod) to provide the file contents inside of your Perl program.

Show the output (including the verbatim text of any messages) of your program.

Describe how you want the output to be different from what you are getting.

If you have no idea at all of how to code up your situation, be sure to at least describe the 2 things that you do know: input and desired output.

Do not provide too much information
Do not just post your entire program for debugging. Most especially do not post someone else's entire program.

Do not post binaries, HTML, or MIME
clpmisc is a text only newsgroup. If you have images or binaries that explain your question, put them in a publically accessible place (like a Web server) and provide a pointer to that location. If you include code, cut and paste it directly in the message body. Don't attach anything to the message. Don't post vcards or HTML. Many people (and even some Usenet servers) will automatically filter out such messages. Many people will not be able to easily read your post. Plain text is something everyone can read.

Social faux pas to avoid

The first two below are symptoms of lots of FAQ asking here in clpmisc. It happens so often that folks will assume that it is happening yet again. If you have looked but not found, or found but didn't understand the docs, say so in your article.

Asking a Frequently Asked Question
It should be understood that you may have missed the applicable FAQ when you checked, which is not a big deal. But if the Frequently Asked Question is worded similar to your question, folks will assume that you did not look at all. Don't become indignant at pointers to the FAQ, particularly if it solves your problem.

Asking a question easily answered by a cursory doc search
If folks think you have not even tried the obvious step of reading the docs applicable to your problem, they are likely to become annoyed.

If you are flamed for not checking when you did check, then just shrug it off (and take the answer that you got).

Asking for emailed answers
Emailed answers benefit one person. Posted answers benefit the entire community. If folks can take the time to answer your question, then you can take the time to go get the answer in the same place where you asked the question.

It is OK to ask for a copy of the answer to be emailed, but many will ignore such requests anyway. If you munge your address, you should never expect (or ask) to get email in response to a Usenet post.

Ask the question here, get the answer here (maybe).

Beware of saying ``doesn't work''
This is a ``red flag'' phrase. If you find yourself writing that, pause and see if you can't describe what is not working without saying ``doesn't work''. That is, describe how it is not what you want.

Sending a ``stealth'' Cc copy
A ``stealth Cc'' is when you both email and post a reply without indicating in the body that you are doing so.

Be extra cautious when you get upset

Count to ten before composing a followup when you are upset
This is recommended in all Usenet newsgroups. Here in clpmisc, most flaming sub-threads are not about any feature of Perl at all! They are most often for what was seen as a breach of netiquette. If you have lurked for a bit, then you will know what is expected and won't make such posts in the first place.

But if you get upset, wait a while before writing your followup. I recommend waiting at least 30 minutes.

Count to ten after composing and before posting when you are upset
After you have written your followup, wait another 30 minutes before committing yourself by posting it. You cannot take it back once it has been said.

AUTHOR

Tad McClellan <tadmc@augustmail.com> and many others on the comp.lang.perl.misc newsgroup.