Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical
 
PerlMonks  

How (Not) To Ask A Question

by jeffa (Bishop)
on Jun 06, 2002 at 06:46 UTC ( [id://172086]=perltutorial: print w/replies, xml ) Need Help??

How (Not) To Ask A Question

This tutorial aims at helping PerlMonks newbies get the most from posting a question here at PerlMonks, namely the Seekers of Perl Wisdom section. The weapon of choice is example and the target is Anonymous Monk. Going all the way back to Anony's very first question, we will observe a lot of 'less-than-good' questions. None of the links to these questions are meant to degrade any of the original posters, they are only here to serve the purpose of what not to do. Only posts by Anonymous Monk were chosen.

(Note to monks with consideration power - please do not consider these nodes. Repeat - please do not consider these nodes. They were here before consideration and now serve as examples for this tutorial.)

A good thing to do is first take a look at the Worst Nodes by anonymous posters to see how not to ask a question, and then take a look at the Best Nodes by anonymous posters. Focus on root nodes - that is, nodes whose titles are not prefixed with Re:.

Table Of Contents


Know the Rules

If you have not already, you should first read these nodes and then come back to this tutorial.

(OBE) The Perl Monks FAQ
The Perl Monks Guide to the Monastery
Writeup Formatting Tips
site how to

Also, see the off-site "Why Questions go Unanswered" by Dominus. While we are on the topic of other things to read beside this node, note that this is not the first node to address this topic - see the section 'Where To Find More' below if you want more advice.


Consider the Chatterbox Instead (Scratchpad)

First, if you want the benefits of the Chatterbox, you will have to register yourself. Sometimes your question can be answered more quickly in the Chatterbox. No one gains any experience points (XP) by asking and answering questions in the chatterbox - but it's not about XP right? :)

The opposite to this is asking a question beyond the scope of the Chatterbox, anything that cannot be generally asked or answered in 200 characters or less is probably a good candidate for Seekers of Perl Wisdom. An alternative however, is to post your question on your Scratchpad and ask via the Chatterbox for someone to look at it.

Of course, the main disadvantage to using the Chatterbox instead of posting is that it is volatile - that is, it is not permanently archived. If you feel that your question is worthy of being a permanent addition the site and might help others, then by all means post. If you don't know, you can always ask that in the Chatterbox.


Choose a Good, Descriptive Title

This is very important - your title should concisely (and hopefully uniquely) explain the problem. Do not use the name of a function or CPAN module by itself - our janitors will usually fix this problem for you, but you really should try to avoid making them do work (they don't get paid or receive XP for it after all). Also, do not choose titles such as "perl", "Unix commands from within Perl?", "It's dumb but I need an answer", "Seeking help!", or "I have a lot of problems w/ my scripts, but this may be the biggie. Please read" - and do not use your email address for a title. In essence, choose a title that can be searched by other seekers in the future.

Of course, i guess ANY title is better than no title. ;)

If your title starts with the words 'How To', then maybe you should post to Categorized Questions and Answers (Q & A) instead of Seekers of Perl Wisdom. (You should most definitely look at perlfaq first via perldoc - you did read "How to RTFM", didn't you?) "How to replace the string within a string" and "how to invoke unix commands in perl" are examples, but then again, both posters should have perused the Q & A section before posting. If you do plan on posting to Q & A, please look it over and see if your question has already been asked, because if it has, it has already been answered.


RTFM (AKA Show Some Effort)

Now that you know about the alternatives, and have decided that your question does indeed need to be posted, the first step is to do your homework. Read Masem's "How to RTFM" if you do not already know how to do so. The path of least resistance points to crying out for help before seeing if you can find the answer yourself - it is simply easier to do so. But, finding the answer yourself is far more rewarding then having someone hold your hand, and it also prepares you for that one time when you will have to solve it own your own. If you don't know where to start looking, ask someone in the Chatterbox.

By the way - did you ask Perl yet? Don't ask a question dealing with syntax without first running your code through the Perl interpreter - you might get your answer right now.

When you post your question, it is important that you mention if you have RTFMed - tell us what you have read and please tell us what did not make sense to you.

A couple of examples: the poster of "deleting a file" didn't even try to RTFM first. Contrast this with "Help needed understanding global variables in Perl", who obviously did some homework before posting (and note that this is the only good example in this tutorial). One final note about RTFMing - topics that are difficult in nature are somewhat immune to RTFM, because RTFMing by yourself on these topics can really be tough. These topics sometimes either do not have an abundance of information or are just plain hard to understand - but don't worry, you won't be chastised too badly for not RTFMing. The important thing is to show that you did give your problem some effort before you asked. Blessed by those that help themselves, and don't be victim to that other form of laziness.


Be Patient

Impatience is indeed a virtue of Perl, but patience is THE virtue of both asking a question and receiving the answer. If you ask your question too quickly, you will embarrass yourself. If you are too impatient to receive an answer, you might irritate others.

An important component of successful progress is multitasking. If you find yourself at wit's end on a problem that you cannot solve, post your question and walk away from it for a while - work on another problem instead. When you have made progress with your second (or third or fourth) problem, come back. Your question might be answered or you might even be able to answer it yourself. A little time can work wonders, and haste can lead to more errors.

Remember, Perl programming can take quite a long time to really understand - actually, programming in general takes a long time to really understand (see the off-site Teach Yourself Programming in Ten Years). The poster of "Password Protection" didn't want to waste time learning how to program. They got their answer, but if you as a registered user post a question like this, be prepared to receive some negative votes.


Take A Deep Breath

If you are really frustrated from your problem, the first thing to do is relax. Don't let frustration affect your post, like it obviously did on "find the syntax error!!!". Walk away from your problem for at least five minutes, then post. Please don't be tempted to end your post with a remark that can be perceived as insulting.


Conceal Your Desperation

There is no need to express your desperation in your question. We get rewarded for answering your questions as quickly as possible - our reward is experience points (XP) by our fellow peers. Your question will be answered very quickly unless it is extremely hard to understand or your post during a slow weekend or holiday. Of course, we don't really care about the XP - our real reward is helping others in a timely manner ... OK, we do like the XP, but we really do want to help you.


On Grammar and Spelling

You should strive for correct spelling and to be grammatically correct, but these are not necessities - especially if English is your second (or third) language. But, if English is your native language, please don't abuse it with non-abbreviations such as u (you), THX (thanks), and coz (because).

And please, no "1337 5pE4k d00dz", unless maybe you are trying to make a point. We at the Monastery try to make this a civilized society, and some of us will down vote and/or ignore you as a matter of policy.


Use The Preview Button

Do not post without first previewing your question. Once you have posted your question, you cannot go back and edit it. An editor can make corrections, but you should do your best to avoid making them do this. If you have included code in your post, be sure and surround the code in code tags - for example:

    I am trying to copy a single value from a hash, but I keep getting a syntax error. Why doesn't the following code work?

    <code>
    my $home_dir = %ENV{HOME};
    </code>

Remember that < and > tags will be rendered by the browser - if you use them, chances are good that they will not 'appear'. Use code tags or use their escaped equivalents: &lt; for < and &gt; for > (although only the former is really necessary). Also, consider writing your post in a text editor first (and saving the file often), then pasting it into the textarea. If your browser or computer crashes while you are composing in the textarea, you will lose your entire question.

After you have previewed your post, chances are good that you will need to make corrections - preview these as well. A good rule of thumb is never hit 'Submit' until you have previewed your question - preview after every change. When you have made no corrections and everything looks good, preview again. Then submit it.


Avoid Using ALL CAPS

This is always a bad idea. Just take a look at "PERL TO HTML FORM" to understand why. Conversely, no caps is not a very good idea either.


Avoid Profanity

Please refrain from using profanity. Someone might have your answer, but take offense and decide to help someone else instead. After all, this is a monastery, and there are non-adults that view and participate here. Also, many of our audience work in corporate environments. In both cases, these participants may be blocked by filters that they have no control over.

Avoid profanity and avoid the NodeReaper.


Try To Make Sense

Go back over your question before you post and ask yourself this question: "Does my question make sense to me?" If it does not, then it most assuredly will not to others. Refer to 'Take A Deep Breath' above. By that same token, posts that make sense but are hard to follow are not going to get a good reception either. Read over your post again, if you pass out from lack of oxygen because you don't have time to breathe - rephrase your question. Try to not be vague.


It's Perl!

Not PERL, not perl, and most definitely not pearl. Perl. And while we are at it, please don't post questions that have nothing to do with Perl. (Although we do get a good chuckle every once in a while.)


Don't Give Us Your Email Address

This is a forum, not a mailing list. If you post your email address, then you are only going to allow spam bots to find it and add it to their spam lists. If you take the time to register yourself as a user, you can go to your User Settings and check the box that says '/msg me when there's a reply' under the Miscellaneous options to receive a private message when someone replies. Otherwise, check back in about 10 to 20 minutes, and then once every hour until you have an answer that satisfies you. You should also check back the next day and maybe even the next week - you never know when someone will post a 'late' response that is very helpful and informative.

Likewise, don't ask us to post our email addresses either.


Don't Post Sensitive Data

This includes PASSWORDS! If you have a database question, be sure and remove your user name and password from your posted code. Also, don't post real email addresses, the recipients of those email addresses will appreciate you not doing so. Go over your data and make sure that you have removed all sensitive data first. Our janitors are very good and will remove these for you, but not immediately - and it only takes a few seconds for some evil doer to obtain that information. This is your responsibility, not ours.


About CPAN Modules

We here at the Monastery live by the CPAN - but at first, the CPAN is not so easy to use. We can help you. Let us know what platform you are on - Windows or some flavor of Unix/Linux. Questions that contain statements like "I can't install CPAN modules" or "I don't like using CPAN modules" are going to be chastised. If you really feel that you cannot install CPAN module, either because you don't know how or your Internet Service Provider will not let you - then read "A Guide to Installing Modules" first. If you insist that you do not need a widely used and cherished module for your problem when others have clearly shown you why you do, then be prepared to be flamed.

Also, it helps to tell us which module is giving you trouble, although the collective deduction skill of the Monastery is rather impressive.


Only Post Relevant Code

Questions that post only the relevant snippet of the program will be answered much sooner than questions that post the entire program. You should take the time to to write a unit test of your problem - instead of trying to solve a small problem in a large program, write a small program that focuses on the small problem. If that doesn't work, then post your question - not only will your code be (hopefully) easier to follow, but your question will also be more focused.

Watch out however, if you don't post enough or don't post any code at all, you might not get the right answer you were looking for. Also, don't post only code, and if someone is trying to help you and asks for some code snippets, they mean snippets - not the entire program.

Remember that just posting your code is not going to get your question answered. If you don't tell us what is wrong, not just that your program does not work, we have to guess. "It doesn't work" is not a very good explanation (some would say it is not an explanation at all).


Include Sample Data (I/O)

Code by itself might not be enough, you should also include what your INPUT looks like, and what your desired OUTPUT should be. For example, if you are having trouble parsing a CSV file, you should at least list what the fields you are trying to parse are. Including a few lines of the CSV file is usually a good idea as well, but please don't post the whole CSV file (unless it is very, very short).

Providing output can be helpful too, especially when asking about data structures. A dump of your data structure, via the Data::Dumper module, will more than likely be helpful.

Also, if you are using a non-standard program to gather system output, include a sample of what this output looks like. This is very important because if you don't, only those people who have that non-standard program will be able to help you. By providing sample data, you are increasing your audience - your problem could be very simple, but without knowing what you are parsing, your question could go unanswered.


Error Messages

Letting us know what error messages are generated can be helpful - or harmful. If your script spits out lines and lines of errors, do not post the entire output of your errors. Deal with the first few errors first, worry about the others later - as a matter of fact, if you correct those first few errors, some of the later ones will 'go away'. Also, posting only the errors is not very helpful either, and will only hinder our ability to answer your question.


Clean Your Room

Ovid says it much better than i can: "Clean your room!"

And while we are on the subject, you will get a much better response if you take the time to make your posted code look nice. Taking the time to properly indent your code before hand will save time for others. Consider these two examples:
Bad:
while (<STDIN>) { chomp; if ($_ =~ /hello/) { &style1(); } else { &style2(); exit; } } sub style1() { print "hello\n"; } sub style2() { print "bye\n"; }
Good:
while (<STDIN>) { chomp; if ($_ =~ /hello/) { &style1(); } else { &style2(); exit; } } sub style1() { print "hello\n"; } sub style2() { print "bye\n"; }
There are no rules that say you have to cuddle your opening braces or isolate them on the line below (style1 versus style2 from the example on the right) and both are accepted - the important thing to do is be consistent. Consider running your code through perltidy before posting.

(and don't forget to use strict!)


<pre> Versus <code> Tags

When in doubt - use <code> tags instead of <pre> tags. If you are new, please stick to <code> tags only until you have made a few posts and/or really feel that you understand what the difference is.

Use <code> tags for code - use <pre> tags for data and error messages - this makes downloading the code just a little bit easier for the people trying to help you. However, if the lines of your data or error messages exceed 70 characters, you should either use <code> tags or insert newlines to break your long lines into smaller lines. A good rule of thumb is if you cannot see the nodelet section on the right of the preview page (i.e. if you have to scroll to see it), then you should format your question so that you can. Again, consider using <code> tags instead of <pre>.

Also, do not post your entire question in either code or pre tags. Try to make your post look nice.


Use <br/> Tags VERY Sparsely

<br/> tags are usually unnecessary. Most of the time, people use <br/> tags because they have a wide width for their browser and they think they are doing others a favor - but not everybody uses the same browser dimensions, so let the browser handle the width formatting. Use <p></p> tags instead of <br/> tags.

99.99% of the time, <p></p> tags and lists (<ol></ol> and <ul></ul>) are all you need. Just make sure you close your tags, otherwise you will effect formatting for the rest of the thread.

In general, try to make your post look well formatted. "Parse an URL" is a node that could have benefitted from better formatting. Again, the poster's question was answered, but a hard to read post will not get a lot of attention. Especially if you misuse HTML tags.

If you do use the br tag, please use <br/> and not <br>. Likewise, you should also close your p tags. See W3C for more information.


Off-site Linking

Don't. Off-site linking is usually acceptable for nodes that can be edited by their author, but since your question cannot be, you cannot come back and fix the link when it breaks. Off-site linking is best as a supplement to your question, not as a replacement, but you really should have a very good reason to use off-site linking if you do so.


Do Your Own Work

Asking for help is one thing, but requesting us to just do your work for you for free is not going to happen - you should ask the kind folks at the perlguru's I need a program that... forum instead.


About Homework

Most of the time homework questions are called out, but there is always one or two XP whores eager to answer them. Just remember, if you do get a homework answer from us, you are only cheating yourself (and good luck on your exam ;)). Also, you will get a better reception if you do announce that your question is indeed homework, and please take some advice from a professional college student, talk to your teacher or professor - that is really what they are there for.

And please don't belittle your "lecturers" - they might find out (especially if you leave your school email address behind).


Weekends Are Slower

There is more activity during the week than the weekends. However, this does not necessarily mean that your question will remain unanswered, it just means that there are generally less people logged in. Sometimes posting on the weekends (slower traffic) can be better than posting during the week (heavier traffic) because your question will not be competing with a plethora of other questions.


Uncharted Territory

Understand that questions dealing with cutting-edge topics might never be answered. The newer a subject is, usually the smaller the audience, and hence the less likely that you will receive an answer. I myself have fallen victim to this one, and my best advice is to keep searching if you do not receive an answer.

Ask anyway, because even if you do not receive the answer you were looking for, you will probably receive some helpful hints. And if you do find the answer on your own, please feel free to post it as a reply to your own question in hopes that others will benefit from it in the future.


The Front Page

Seasoned monks rarely look at the front page, AKA, The Monastery Gates. Instead, we watch the Newest Nodes page like hawks (this is a form of 'XP Whoring'). Your question will not appear on the front page unless a higher level monk has deemed it worthy to be there - but don't worry, it will appear on Newest Nodes. Be patient.


Don't Worry About XP

Don't ask a question for the sole purpose of gaining XP - ask a question to get an answer. Also, don't post responses to each and every reply that you may get - sometimes a private /msg is all that you need. Think about the big picture: what others are reading. Does your reply to a reply further your personal needs or is your reply truly relevant to others. If a reply to your question does not answer your question, go ahead and post a reply to it - but do not insult the person who tried to help you. If you are a registered user with votes, the decision is yours to down-vote an incorrect answer, but please remember that it is human to err, and unless the answer was particularly insulting, there are plenty of good nodes that need up-voting that you could spend that vote on instead.


Be Patient (again)

Now that you have posted your question - just sit back and be patient. Advertising your question in the chatterbox is an annoyance - we XP whores know it is there. We XP whores sit diligently waiting for new questions to appear in hopes to gain more experience. Be patient. If your question has not been answered in 24 hours, then you could advertise it the chatterbox because it is very possible that the one person who can answer it did not see it the day before. But don't push it, because chances are higher that your question either did not make sense to us, or no one genuinely has the answer (uncharted territory). Consider inquiring in the Chatterbox whether or not if your unanswered question made sense to others.

The other more serious annoyance is re-posting your question, and i don't mean accidentally double posting. Of course, triple posting is right out! ;) If your question was not answered, re-posting the same question is not going to help.


Following Up

If you do find the answer, there is nothing wrong with posting a 'thank you' to let everyone know that your problem has been solved. Even better - summarize your solution path and post that. This method is certainly more preferred than posting a reply to each and every reply, which can be perceived as an annoyance.

Sending a private /msg is also appropriate, but sometimes it is nice to let everyone else know that your problem has been solved - and you cannot send a private /msg if you are not a registered user.

Also, please do not mistake critique for criticism. The site is privileged with a lot of highly skilled programmers, and if one of them gives you advice on coding or design style, you should listen. If you do not know whether to trust their advice or not, be patient - someone else who does know will call them out if they are wrong.


Be Nice

Indeed, "don't argue with the people you've asked for help. If you aren't going to take their advice, don't waste their donated time by asking it." Better to simply move on rather than start a flame war.

"Do unto others as you would have them do unto you."


Don't Be Afraid

Don't be afraid to post. Don't worry if your English is not very well written. Don't worry if you are new to Perl. Most of us are understanding and will not make fun of you - those that do will be punished with negative XP and a possible encounter with the NodeReaper. If you stick to all the points presented in this article, your question will be well received and hopefully answered in a more than timely manner.

There is certainly nothing wrong with lurking, but you can learn a great deal more by actively participating. More importantly, you can help others learn a great deal more as well.


Where To Find More

This tutorial is by no means the first The Monastery has seen of this topic. ybiC has assembled a wonderful list of past posts that cover this topic. See the 'Questions' section on his home node. Also, turnstep's home node also has a lot of valuable information that will help you get the most out of PerlMonks.


Credits (AKA Thank Yous)

A big thanks to ybiC, danger, demerphq, and Ovid who added their excellent input. Also, a big thanks to the following monks, without whom this tutorial could not have been written:

belg4mit, broquaint, chipmunk, chromatic, davorg, Dominus, dws, footpad, kudra, Masem, mirod, mpolo, merlyn, neshura, particle, petdance, Petruchio, rob_au, tachyon, tilly, turnstep, tye, vroom, vnpandey, and any of the janitors i forgot to mention. Thank you all.

Replies are listed 'Best First'.
Re: How (Not) To Ask A Question
by cLive ;-) (Prior) on Jun 06, 2002 at 07:11 UTC

      I always found that article condescending. Here’s a new guide that I’d link in great preference to ESR’s screed: Getting Answers. It’s geared towards the benefit of the one doing the asking, unlike most guides, which are geared towards the benefit of the ones answering.

      From the introduction:

      Other people have written articles on this subject before, but they suffer from problems. My goal is to avoid those problems and make something that’s directly useful to you, the person with problems, rather than something that’s mostly useful for the people answering the questions.

      How To Ask Questions The Smart Way is pretty condescending, especially if you already feel insulted by somebody telling you that you need help asking questions. If you’re pointed at a guide with a filename of smart-questions, that means this person thinks you have stupid questions, and who needs that?

      Help Vampires: A Spotter’s Guide is great, but it’s written from the other side. While it’s great for people who hang out and answer a lot of questions, and helps them deal with the titular Vampires, it’s not something that’s very useful for a person asking questions.

      Another guide I just discovered is GettingHelpOnIrc. It’s a handy companion to this one, although more geared towards the nitty gritty of IRC etiquitte and less towards the actual questions.

      And so I present to you Getting Answers. The goal of the article is to get answers to your questions, nothing more and nothing less. I’ll completely ignore boring stuff like the proper way to greet people or when to read the topic. This guide will walk you through ten basic things you can do to increase the chances of getting answers, and increase the quality of the answers you get. Getting a reply of rtfm! is considered failure, no better than no reply at all, and getting advice that solves your problem is success. All else is secondary to that.

      Makeshifts last the longest.

Re: How (Not) To Ask A Question
by chromatic (Archbishop) on Jun 07, 2002 at 14:47 UTC

    Under "Be Nice", you might add "Don't argue with the people you've asked for help. If you aren't going to take their advice, don't waste their donated time by asking it."

    I'd be disinclined to help a few users that have broken that rule, if I could remember their nicknames. :)

Re: How (Not) To Ask A Question
by jsprat (Curate) on Jun 06, 2002 at 18:42 UTC
    Whew! You spent some time on this one, great work. I count 36 separate points. Three ideas:
    1. Can this be included in the site documentation?
    2. It needs a table of contents, linking to each topic
    3. "Choose a Good, Descriptive Title" belongs closer to the top of the page. Does anyone else roll their eyes at the "Newbie question" nodes?
    Anyway, ++jeffa
Re: How (Not) To Ask A Question
by boo_radley (Parson) on Jun 07, 2002 at 19:45 UTC
    Unless I hear objections to it, I'll be adding this to the perl monks faq by 12JUN2002.

      I did not object because you left my name on the the copy. Now my name has been removed. What a slimy thing to do.

      jeffa

      L-LL-L--L-LL-L--L-LL-L--
      -R--R-RR-R--R-RR-R--R-RR
      B--B--B--B--B--B--B--B--
      H---H---H---H---H---H---
      (the triplet paradiddle with high-hat)
      
Re: How (Not) To Ask A Question
by amarceluk (Beadle) on Jun 06, 2002 at 19:02 UTC
    Excellent! I agree with jsprat, this would be a valuable addition to the site documentation.

    __________
    "Abby-somebody. Abby-normal."
    Young Frankenstein
Re: How (Not) To Ask A Question
by chromatic (Archbishop) on Nov 19, 2006 at 00:40 UTC

    I have a difficult time seeing this as "good" code:

    while (<STDIN>) { chomp; if ($_ =~ /hello/) { &style1(); } else { &style2(); exit; } } sub style1() { print "hello\n"; } sub style2() { print "bye\n"; }

    There's inconsistent brace styling, the useless use of & on subroutine calls, useless prototypes, and a useless use of $_ =~. I'm not sure if explictly using STDIN is helpful either; it depends on the intent of this program. I hate to miss out on magic ARGV behavior. I'm also not sure that chomp has any value in the code snippet.

    How about:

    while (<STDIN>) { unless (/hello/) { style2(); exit; } style1(); } sub style1 { print "hello\n"; } sub style2 { print "bye\n"; }
      The brace issue appears to be deliberate, according to the note below that code snip:
      There are no rules that say you have to cuddle your opening braces or isolate them on the line below (style1 versus style2 from the example on the right) and both are accepted - the important thing to do is be consistent.

      ----Asim, known to some as Woodrow.

Re: How (Not) To Ask A Question
by Anonymous Monk on Jul 02, 2009 at 02:24 UTC
    use Devel::Modlist; to provide a list of modules used and their version numbers
Re: How (Not) To Ask A Question
by ambrus (Abbot) on Jan 22, 2013 at 18:49 UTC
      But contrary to the FAQ does the original have a TOC with deep links like RTFM (AKA Show Some Effort) ¹)

      Cheers Rolf

      ¹) sorry for the absolute link, but [id://172086#rtfm] doesn't seem to work

      UPDATE

      OK found a way ?node_id=172086#rtfm

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perltutorial [id://172086]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others cooling their heels in the Monastery: (2)
As of 2024-03-19 06:28 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found