A recent chatterbox discussion brought up the notion for a meditation on how to ask for help. I assumed there much be such a beast, but I didn't find it after a brief search (perhaps such a thing belongs in Perl Monks Site FAQ). The following is only intended as a starting off point, I hope others will followup with their own bits of accumulated wisdom

Suggestions on asking for help.

0: Rationale:

This is often not a terribly high volume forum but there are still quite a few posts on occassion and the better you formulate your query the more chance you have of someone taking the time to read and answer your query or at least point you to a useful resource. This posting is provided to help you formulate queries that are likely to be read, answered, and perhaps even ++'d.

Some of these may seem like common sense, other's less so -- I'm not trying to insult anyone's intelligence with the common sense variety nor force feed these down anyone's throat (they are merely suggestions).

1: Subject Header

The subject header is a vital piece of information -- the content of the subject header should tell us (to the best of your ability) what the focus of your query is. The following are not good examples:

    Urgent: Help needed!!!
    CGI problem
    Why doesn't this work?

The reason these are not good examples is that they don't provide us any information regarding the nature of the problem. If your subject isn't informative, it may be a sign that your whole post isn't going to be well thought out either. Here are some better examples:

    Regular expression trouble
    Data extraction problem

But, even here the subjects might be considered a little vague. Some even better examples might be:

    Removing duplicate array elements
    Regex to match IP addresses
    Extracting columns/fields from data

Now we have a pretty good idea about the question and our minds will already be operating on potential answers even while we open up your posting. In short, try to be as specific as possible about your task or the Perl construct that is troubling you.

2: Body content

Being specific here is even more important. You need to really think about your problem and spell it out in plain english. If your query, or task, involves data inputs and outputs then by all means, include a representative example of inputs and outputs. If your query refers to a Perl syntax error, or warning then you need to include the text of that error/warning as well as providing the code that causes that message. Which brings up a second point about content -- providing a relevant code snippet. Sometimes you may have a largish program that is giving you trouble -- try not to post the whole program, just the portion relevant to the problem. Better yet, try to code a small and self-contained program that uses the construct and exhibits the same behaviour -- quite often this step alone will assist you in finding, and correcting, your problem without posting a query at all.

Any included code should not be typed into the message, you should cut and paste, or otherwise insert, the real code into the message. No one wants to waste time finding your typos (if they aren't the real problem).

Perl has two features to help you find problems in your code: the -w switch, and the 'strict' pragma. If at all possible, start your code with the following two lines:

    #!/usr/bin/perl -w
    use strict;

(adjusting for your real path to perl). These will help you avoid or at least locate many problems in your code. If you are replying with code, using code that is -w and strict compliant is a good idea, and testing your code before posting is highly recommended.

3: Checking other resources first

Perl comes with a very large amount of documentation that is sitting right there on your hard drive for you to use. Learning to make good use of this resource is very important. This documentation takes the form of manpages, HTML pages, or some other form depending on how it was installed. Whatever format(s) it was installed in, it will still be available to you as plain POD files and can be accessed using the included perldoc utility. For example, in a shell or console window:

    perldoc perl     <== brings up the introductory perl manpage
    perldoc perlfaq  <== brings up introductory faq manpage
    perldoc perlre   <== brings up the perlre manpage
    perldoc perlfunc <== bring up the perlfunc manpage

Additionally, individual entries in the perlfunc manpage (where perl built-in functions are described) can be accessed directly using the -f option for perldoc:

    perldoc -f sort  <== brings up the entry for the sort() function
    perldoc -f eof   <== brings up the entry for the eof() function

Part of the included documentation is a set of FAQ pages, numbered 1 through 9 (perlfaq1, perlfaq2, ..., perlfaq9). These contain entries consisting of questions that have been asked often in the past (and, unfortunately, are still often asked because people don't read these faq pages). They are extremely useful documents that you should read or skim through at least once. The perldoc utility may also be given the -q option to search the faq pages for entries containing a given search term:

    perldoc -q sort  <== shows all faq questions containing 'sort'

Now, no one here is suggesting that you read the whole documentation set before you begin programming, or before you ask a question. That would not be very practical (but no one will fault you for it if you do). However, it is to your own benefit to familiarize yourself with those docs because once you do you can often find answers far faster than posting to the forum. It is a good idea, if you do look over the docs first but don't understand the information given, or don't find the necessary info, that you say so in the post -- this allows those who reply to know whether you just need info pointing to the correct place in the docs, or whether you need something explained in better detail.

In addition to the documentation being included on your hard drive, it is also available right here on perlmonks: perlman:perl, perlman:perlfaq]. Using the Super Search feature will not only let you search those documents, but all of perlmonks as well.

Learning to use the available documentation and resources is an integral part of learning to be a programmer.

note: Tom C also apparently has a replacement for perldoc named 'perlman' -- I've not yet looked at it, so perhaps some kind monk will discuss it in a followup.

4: Other remarks.

One additional thing to think about when formulating a question. The question should focus on the underlying task or goal, not the method you are currently attempting. For example, let's say you are working on trying to find out if an integer is odd or even. You know that an even integer divided by two is an integer, but an odd number divided by two will have a decimal portion (.5 in fact). So, if we divide an integer and the result ends in .5 our integer must have been odd. So you decide this will be a good way to do it but you are not sure how to make such a test, and you post a question asking how to test if a number ends in a decimal portion, or ends in a .5. You'll surely get replies for various ways to do it -- but since you never asked about the underlying task you'll never get answers about better methods to test if a number is odd or even (and there are some).

5: Epilogue

    There ain't nothin' in this world that's worth being a snot over.
        -- Larry Wall in <1992Aug19.041614.6963@netlabs.com>

'nuff said

Replies are listed 'Best First'.
(kudra: combine with existing docs?) Re: On asking for help
by kudra (Vicar) on Jan 08, 2001 at 17:41 UTC
    Perhaps it might be more logical to suggest other resources before talking about how to write a post? That section could also contain a mention of the resources at this site, or a link to a page that describes it.

    I also think that the point on the message body is incomplete without a link to the page that describes how to properly format your posts.

    As others mentioned, this subject has come up before (jptxs got the other link I remembered, but I'm sure there are more). I'm not really sure that an additional 'line of defense' is needed because those that want to read the docs will read them, and those that don't want to won't. I could see a document like this being integrated with existing documentation to make a clearer introduction, however. Maybe you should consider trying to join the site documentation clan if you have an interest in this sort of thing? (Note that I do not belong to that group, so I have no idea if this is a valid suggestion or not--hence the 'try').

    In response to Maclir's suggestion, I'm opposed to the idea of requiring people to register in order to use the site properly. I think people are entitled to privacy if they want it, and right now I don't think poorly written anon posts are a big enough problem to warrant such an extreme solution. I'm sure this, too, has been discussed before, but I can't remember when.

      I agree completely with respect to the whole anonymous monk issue. Registration does not guarantee quality posts. See also: Slashdot, ZDNet.

      The only thing that would be helpful along these lines is a user option for "no posts below ##" so that I can set a minimum reputation level, if I feel like I'm overwhelmed by the noise.
        ichimunki, I have to disagree. Unlike /. were only a few can moderate, here we all can. It's not just a way or expressing ourself, but also our duty to the monestary to sort through nodes and rate them.

        If a new node comes in with a rep of 0, then anyone who has a positive threshhold don't even see it, so until someone else does their duty, you are not even aware of it except as some footnote that there are messages under your threshold.

        /. gets around this by a) restricting who can moderate at any time - hopefully they'll be reading with a low threshold, b) allowing posters to start with a positive "rep" (+1 for those logged in, more for higher level posters). Whether this model works for them, is it what we want here?

        I'm being a bit specific to /. since that's where I have the most experience besides PM, but I'm sure you n think of other examples that fit my points.

        ...you might be eaten by a grue...

($code or die) Re: On asking for help
by $code or die (Deacon) on Jan 08, 2001 at 07:25 UTC
    I think this is a great post. Importantly it sums up the good things about Before You Post....

    There have been quite a few meditations on this subject before. I think the problem has been new visitors to PerlMonks don't always check the Perl Monks Site FAQ or instructions on how to post. There are often posts in the wrong place/multiple posts and posts without <CODE> tags.

    I am not sure if another site FAQ is the way to go if it won't get read. But, I think that this node is great and should be emailed to new subscribers when they get their password.

    BTW, I just screwed up and posted a new meditation instead of replying to this one. So even (supposed) 'experienced' Monk's screw up sometimes!

    I will try and think of another meditation and not let it go to waste!
(jptxs)Re: On asking for help
by jptxs (Curate) on Jan 08, 2001 at 09:10 UTC
    I second the spirit and content of this post! This is exactly the kind of thing we need. I suggested a simlilar idea in a /msg for all first timers, but if a node like this existed, we could simply /msg first timers a links to it first. I could even see putting this node in the menu of choices after a user clicks "Need Help??" as a first line of defense for silly questions. (maybe it could also have the side effect making people realize this isn't a gossip site...)

    bravo and ++ (when i get my votes again =)

    "A man's maturity -- consists in having found again the seriousness one had as a child, at play." --Nietzsche
Re: On asking for help
by arturo (Vicar) on Jan 08, 2001 at 20:20 UTC

    In general, this is excellent advice. What gets me is that most of it has been given before (albeit the advice is a bit scattered around); the question is "how do we get this message out to cut down on the poorly asked questions?" (since that is the goal)

    Rather than banning anonymous posting outright, perhaps an anonymous poster should be forced to click through a page such as yours before being given the form to post? A benefit of this is that we'd get less "you don't have to get snotty" retorts from AMs when a monk says "well, if you'd just tried 'search' you'd see this has been answered 17 times already."

    With registered users, the "informational page" option could be on by default, and for those who turn it off and post badly, well, voting is there to do the work that the info pages weren't able to do.

    What do monks think about that?

    Philosophy can be made out of anything. Or less -- Jerry A. Fodor

Re: On asking for help
by danger (Priest) on Jan 08, 2001 at 09:05 UTC

    Oops, didn't notice that the Wall reference was eaten as a tag, it should have read:

    5: Epilogue

    There ain't nothin' in this world that's worth being a snot over. -- Larry Wall in <1992Aug19.041614.6963@netlabs.com>

    'nuff said

Re: On asking for help
by Maclir (Curate) on Jan 08, 2001 at 09:07 UTC
    A truly excellent set of guidelines. Now, the challenge is how do we get people to read (and hopefully understand and follow) before they mindlessly post?

    I wonder how feasible it is to remove a person's posting capability until they have read a particular node? A person coudl surf the Perlmonks site as much as they liked, but until they had a registered userid, and that userid was recorded as viewing the faq pages, they could not post any questions. I know this means "anonymous monks" could not post - or make replies - would that be an acceptable consequence?

      Hmm, i may be wrong, but I don't think this was written in response to people "mindlessly posting" stuff. I think it was more of a concrete guideline for newbies (granted, who sometime don't read site FAQs etc). You should refrain from negative comments like that, as it can be misinterpreted as elitist, old-boys network, etc, etc. Just my one cent. Thanks Jim
      if ($mr_leisure) { bow; }
      this is still not finished