Beefy Boxes and Bandwidth Generously Provided by pair Networks
XP is just a number
 
PerlMonks  

RFC - How to ask...

by ww (Archbishop)
on Feb 14, 2009 at 11:51 UTC ( #743806=perlmeditation: print w/replies, xml ) Need Help??

Update: 2009-02-15 ca 1730 GMT: THIS VERSION IS NO LONGER CURRENT.

FOR A CURRENT VERSION The current version -- improved by the many folk who've replied or /msged about this -- has been posted to How do I post a question effectively?. Since we anticipate additional improvements, please check that and /msg SDC. Thanks


 

How to ask a question effectively

This is a little long. But, please, at least scan it. It's our best effort to help you get help. These are not "rules for the sake of rules" but, rather, guidelines to help you help us to help you.

So here we go (and eventually, we'll even get around to "Where to ask?"):

First and foremost, think through your question.

  • Can you explain it clearly to yourself?
  • Can you explain it to others?
  • What example data would help them understand the issue?
  • What's not happening that you think should happen, or happening that you think should not (or don't understand)?

Write it down -- preferably in your editor on your machine.

Look away for a moment; perhaps mull the question over some more.

Edit for clarity and precision (leet-speek iz rong on both cnts!). Spelling and grammar count (but we try hard to understand if English is not your native tongue).

Repeat as necessary. It's often said and often true that explaining a problem to a rubber ducky or to a teddy bear will show you a solution.

Show us that you've made an effort.

  • Show your code (at least the problematic snippet)
  • Explain in detail what you get (include sample output, error messages and warnings, for example).
  • Tell us how your output means your script isn't working.

If you do, it's likely someone will provide pointers in the right direction.

Now you're getting close to a good question.

But before you post it, take another step. Include (inside <code>...</code> or <c>...</c> tags) a minimal, compilable script that demonstrates your problem and sample data (input).

Use strict and warnings. If you don't, and your sample code throws errors or warnings, NodeReaper (or some solicitous Monasterian) will throw that in your face.
Failure to use strict and warnings is a red flag; it tells us you didn't use the available tools ("aka, make an effort").
On the other hand, using these pragmas may show you how to solve your problem before you post. For example, they'll catch variables where you make a typo between assignment and use. Failure to use them is like ice-climbing without a safety line.

Again, use code tags without fail or the Monks' outrage may lead them to conclude, prayerfully, of course, that you need penance. In fact, failure to use at least minimal markup will almost certainly persuade some of the Reverend Brothers and Sisters to point you to the sackcloth and ashes in the third sub-dungeon. ( See Markup in the Monastery for quick reference or Perl Monks Approved HTML tags for an exhaustive list of what's allowed.) And be sure to close your tags; the special dialect of html used here is unforgiving about failure to close some tags.

Preview. See if what the preview screen shows looks like what you intended. And if it doesn't, fix your markup, and preview again. ONLY when your note "looks right" should the "Create" button tempt you.

Select an informative title. "Need help ASAP" doesn't cut it. Neither does the name of any Perl function.
For example, if you're having problems dereferencing an array in a hash, SOPW won't accept a one word title like "%hashref"; %hashref problems" isn't fully descriptive; but "Why doesn't this deref the @arrays in my %hasref?" is probably OK.

OK, but what was that 'or not' business about?

Ah, I'm glad you asked.

Laziness is one of the virtues admired by Perl programmers -- in themselves or when demonstrated with competence and verve! It is not admired when demonstrated by a Seeker of Perl Wisdom who is too lazy to adhere to the hints above; who posts ambiguous questions; who fails to read the docs (see perldoc perldoc for an overview of the knowledge that's at your fingertips; or who inconveniences thousands of electrons to ask redundant questions.

But I never asked that question before!

No, but surely you don't think you're the first to come to the mountaintop seeking that wisdom, do you?

Super_Search is your friend. Use it! Or Google PM. Big G is quite good at finding nodes here that will help you, if you ask with reasonable search terms.

But I'm new at this; I don't know what search terms to use!

Ah, that plaint is sometimes justified, but have you RTFMed How to RTFM? Did you look at the plethora of information available via perldoc or at perldoc.perl.org? The Tutorials may also speed your search for enlightenment.

And a few scattershot points:

  • Log in before you post unless you want it to be anonymous (and remember that that anonymonk can't update a node nor get notifications of replies)
  • Don't ever wipe the original content of any node you've written, even if you've solved your problem; you're clarifying your issue; or you realize you just made a "D'oh!" Mark the changed/new content with the word "Update." Don't delete! Doing so is likely to make replies you've received unintelligble to future readers. Use <strike> ... </strike> if you must.
  • This is PerlMonks. Stay on topic. This is not the place to ask about bugs in your javascript (or the other 'j' language) nor how to learn write a formula in a spreadsheet, even though there are many Monks knowledgeable in such disciplines.
  • Be patient. And don't tout your node in the CB.
  • Don't post real email addresses, usernames, or passwords
  • Own up to homework. (We may help with homework when you show some effort, but you're not learning anything and we're not helping if we do it for you.)
  • Understand that the Monastery is NOT a code-machine. Don't ask for a handrolled script to suit your needs. That costs $$$$.
  • RTFM -- the various FAQs, guidance and tutorials on our standards, as well as those on Perl.

More to come... Suggestions to ww.

 

But all I wanted to know is "where to post my question?"

There's a form at the bottom of the Seekers of Perl Wisdom page (but first, please go back to the top and actually read the suggestions).

Wow! How can I thank you enough?

Adhere to these suggestions... and pass them on to others.


What would you add/remove/change? (   Given the date of posting, note that valentines and brickbats are equally welcome. :-)   )

Replies are listed 'Best First'.
Re: RFC - How to ask...
by ELISHEVA (Prior) on Feb 14, 2009 at 17:44 UTC
    Four suggestions:
    1. I noticed some jargon terms (SOPW, RTFM, etc) weren't spelled out the first time they were used - might be a good idea to do so.
    2. Re: compilation. I think we should include a reason (beyond "we think you are being lazy if you don't"). I can think of several reasons we could offer:
      • Sometimes just making the code compile solves the problems on its own (compiler = rubber ducky?).
      • If your code doesn't compile, we may get so distracted by the compilation problems that we miss your real problem.
      • We are helping from a distance. We can't check your system to see if what we offer will work for your specific environment. Only you can do that work, and to do so, you need to have compiling code. (BTW it is ok to ask for help if you can't figure out why something won't compile. But let that be your question then and save the "my script won't do X" question for later.)
      • The best way to learn to program is "code a little, run a little". That's hard to do if your code won't compile. Learning is what Perl Monks is about.
    3. One thing I liked about the old version was that the author went through the archives and pulled out posts that illustrated both do's and dont's. Maybe we could add some specific examples to illustrate your points?
    4. To handle the "This looks a little long *bing*" issue - use a pyramid organization. Make sure the above the fold portion very briefly covers the main points, and is energetic and maybe even funny. Then in an intro section elaborate. Then if you need to, add additional sections going into detail about each bullet point in the intro.

    Best, beth

      ELISHEVA:

      Re your second bullet, "BTW it is ok to ask for help if you can't figure out why something won't compile. But let that be your question then and save the "my script won't do X" question for later."

      I think we should adopt that! ++!

      Re "3" Did you just volunteer to find some really bad nodes (beyond those that don't offer code) that never drew Janitorial attention? Why thank you very much!

      Re 4: Candidates for "above the fold" seem to be pretty numerous:

      1. Think your problem through
      2. code tags
      3. Preview & fix, preview & fix, preview...
                ooops, now we gotta get to a link on markup
      4. Super Search

      That seemslike an absolute minimum. OTOH, maybe I'm getting carried away with that list; how say others?

      Or would an abbreviated TOC (maybe with with one line of info) for those and other important (if not quite "key") points be a good introduction, "above the fold?"

        Re 3: I'll keep my eye out for some anonymous posts that fit the bill.

        Re: above the fold: Your suggestions sound good. The general checklist provided by whakka might be another option. I think the main work here is prioritizing: working together to get a read on the top 3-4 things that will give the first time or newish poster biggest payoff. Also I think we need to avoid "shouting" in the lead - entire sentences in bold is only one step away from all caps. It is not likely to invite people to read on for more details. (just my opinion).

Re: RFC - How to prod newbies
by tye (Sage) on Feb 14, 2009 at 18:44 UTC

    Thanks for contributing this (of course). I'll just quickly address what I consider the most critical points:

    Don't bury the lead. Keep it short. Don't require scanning.


    If you want to get good answers:

    Paste between <code> and </code> tags actual code that reproduces the problem and state exactly what the problem is and exactly what the correct behavior / desired output is. Additional background about what you are trying to do and why along with other things you have tried also helps.

    For example:

    <code> use strict; use warnings; ... </code> gives me the error <code> ... </code> I'm trying to ... <p> I also tried ...

    If you don't have code (link)... If you don't get an error message (link)... If your code is too large (link)... If ...


    I'll also try to find a good, short example to replace the "..."s with.

    Rather than require scanning, include internal links so the reader can jump directly to the appropriate section.

    If you have to apologize via "This is a little long" or "scattershot points", then you are writing to the wrong audience. Just fix such problems so no apologies are necessary.

    Thanks again.

    - tye        

      YESSS!   Thank you!

      Your node could be a stand-alone faqlet. Or it could be the lede -- a replacement for the first graf -- while retaining additional detail/explanatory material for those who would actually read on.

      I'm inclined to the second of those, but that may be misplaced pride of authorship, which was not mine alone when first circulated, and clearly isn't mine alone, now.

        Yes, since it wasn't clear, the "(link)"s were meant to represent internal links to subsequent sections or bullet points in the node (though any lengthy material should be separated out to different faqlet).

        - tye        

Re: RFC - How to ask...
by Jenda (Abbot) on Feb 14, 2009 at 14:37 UTC

    We do not only need people to ask well, we also need to encourage them to post again! So maybe we should not scare them just as much in the "Now you're getting close to a good question." section. And remind them right away that a negative node reputation means that there's a problem with the node, not the person. That the fact that we downvoted the node doesn't mean that he/she should go away, but rather that he/she should do better when asking. To help us help him/her.

      re "scare them" -- Perhaps deleting "If you don't, and your sample code throws errors or warnings, NodeReaper (or some solicitous Monasterian) will throw that in your face."

      That would make the para start like this:

      Use strict and warnings. Failure to use strict and warnings is a red flag; it tells us ...."

      Personally, though, I think the explanation re XP doesn't quite fit here and might instead be an estimable addition to Voting/Experience System or The Role of XP in PerlMonks.

      That's largely because I took the liberty of asking a non_Monk, non-programmer (aka SWMBO, who does happen to be a very good editor) to read a very early outline, and got the observation (even then) that it looked pretty long. I thought about adopting the "Chapter 1, Chapter 2..." approach I used in Markup in the Monastery -- where Chapter 1 is a really pithy (or "too truncated" depending on your view) summary of the really crucial points but didn't do so for a whole host of reasons (one of which might be laziness).

        We can't expect people to read too many documents. Besides I'm not speaking about XP, I'm speaking about node reputation. I'm just worried that if a newcomer ends up with a fairly big negative node reputation it might scare him/her away because of perceived hostility of the Perl community.

Re: RFC - How to ask...
by CountZero (Bishop) on Feb 14, 2009 at 16:32 UTC
    I think you are missing "problems" in this part of the text (see bold "problems" below):
    Select an informative title. "Need help ASAP" doesn't cut it. Neither does the name of any Perl function. For example, if you're having problems dereferencing an array in a hash, SOPW won't accept a one word title like "%hashref"; %hashref problems" isn't fully descriptive; but "Why doesn't this deref the @arrays in my %hasref?" is probably OK.

    CountZero

    A program should be light and agile, its subroutines connected like a string of pearls. The spirit and intent of the program should be retained throughout. There should be neither too little or too much, neither needless loops nor useless variables, neither lack of structure nor overwhelming rigidity." - The Tao of Programming, 4.1 - Geoffrey James

      Missing a "problems" is indeed a problem.
      :-)
      Fixed with a "thank you!"
Alternative "how to ask" stub
by Your Mother (Chancellor) on Feb 14, 2009 at 19:19 UTC
    I think it's great that you're working on this. Like tye said, brevity is crucial. Simple, direct language with examples will also go a long way. Many monks and visitors have English as a second (or third... or fourth, you show-offs!) language. Below is a stab at the way I'd approach it. It's a first draft so feel free to munge or poach if you like it.

    How to ask a question on Perl Monks

    First time? Ask your question here: Seekers of Perl Wisdom (SOPW). Scroll to the bottom and enter it under Add your question. There are other sections of the site but SOPW is most likely what you want.

    How to help the monks help you

    Title your question well. The title should contain the gist or subject of your question or problem.

    Examples of good titles–

    • CGI::App session params losing values between redirects
    • Better union of sets algorithm?
    • Do file test operators cache stat calls?

    Titles that are not helpful–

    • HELPPP !!!! ME
    • Good morning, monks

    Your question is being read by others who cannot see your screen, your code, or what you are trying to do. If you want a good answer, you need to give all the information someone else would need to understand the problem.

    Example of a good question–

    Why do selects fail sometimes with DBI

    …I can’t figure out why my selects fail sometimes but work other times. This is my code:

    my $dbh = DBI->connect($data_source, $username, $auth, \%attr); my $sth = $dbh->prepare("SELECT foo FROM bar WHERE baz = '$qux'"); $sth->execute();

    Example of a poor question–

    I'M ON A DEADLINE! PLEEZE HELP!

    Why doesn't my CGI work?

    There is no way to answer that question. 1,000 things could be wrong with a script and "work" is not even meaningful without first knowing what it's supposed to do.

    Use PerlMonks formatting + simple HTML. Put <code>code inside code tags</code>. They are treated specially here. Please do not use <pre>pre tags</pre>!

    (et cetera?)

      But linking to SoPW is probably more helpful to newbies than linking to the actual section. Or at least copy the helpful items from that very short page.

      - tye        

Re: RFC - How to ask...
by whakka (Hermit) on Feb 14, 2009 at 22:37 UTC

    How about a checklist to put at the top of the post, then refer to further details below? The reason I say this is because it's more than halfway down before you recommend to SuperSearch or Google, which I think is the remedy to most of the issue being addressed by this post. Someone too lazy to consider posting etiquette will most likely miss this, and I see it spouted all the time (and I think most of us have been guilty at some point).

    Also, I think there are two distinct types of questions - coding problems ("why doesn't this work?") and advice seeking ("how do I...", "where do I find...", "what's the best way to...", etc.). Much of this post doesn't apply to the second kind.

    Something in this format perhaps (further modification probably needed):

    General Checklist Before Posting:

    1. Is my problem original? Have I searched perldoc and/or the module documentation? Have I used SuperSearch or Google?
    2. Does my question include all necessary information? Can I be more specific?
    3. Do I explain the behavior I'm expecting, or what I'm trying to accomplish?
    4. Does it have a descriptive title?

    Additional Checklist for Coding Problems:

    1. Do I have a simple example illustrating the problem? Does it compile? Does it use strict and warnings? Is it wrapped in <code>...</code> tags?
    2. Do I provide example output?
    3. I'm not asking for other people to do the work for me, am I?

    I know this is all redundant but it may help to have it all at the top, at which point the reader could continue for a more detailed explanation of why these things are important. I also like tye's template for a post and I think it would help to have that presented first as well.

Re: RFC - How to ask...
by CountZero (Bishop) on Feb 14, 2009 at 16:36 UTC
    But before you post it, take another step. Include (inside ... or ... tags) a minimal, compilable script that demonstrates your problem and sample data (input).
    If the problem is that the script won't compile, this seems unnecessary harsh on the poster.

    CountZero

    A program should be light and agile, its subroutines connected like a string of pearls. The spirit and intent of the program should be retained throughout. There should be neither too little or too much, neither needless loops nor useless variables, neither lack of structure nor overwhelming rigidity." - The Tao of Programming, 4.1 - Geoffrey James

      Good point. How about adding -- after "sample data (input)." -- the following?

      Of course, if your problem is that you can't get the script to compile, despite your best efforts -- perhaps because the error message doesn't make sense to you -- go ahead and post the section where strict tells you that you have an error (and, of course, the error message, verbatim).

        If you want this to be really useful (seems unlikely, frankly), brevity is key. The code needs to "reproduce the problem".

        "This is a little long" *bing* large portion of audience reads no further.

        - tye        

Re: RFC - How to ask...
by Bloodnok (Vicar) on Feb 14, 2009 at 17:39 UTC
    Is there any mileage in putting the perldoc.org, RTFM & Tutorials links on the SoPW page - somewhere near the submssion form?

    I, for one, didn't know about the RTFM link... but that's probably a sign that my sig is all too apposite (and maybe also that I didn't realise RTFM was an abbreviation used elsewhere i.e. other than during my apprenticeship).

    It might also be worth mentioning/hinting that if the title is the last thing entered, then there's no danger (CGI permitting:-) of inadvertently submitting the form - I know, I've tried it and now extensively use the feature.

    BTW, since you mention him, I saw Valentine Brickbat yesterday - he passes on his regards & best wishes to one and all :D

    Update

    Added title hint

    A user level that continues to overstate my experience :-))

      Adding the links you mention just above the input box seems like a good idea, but NOT because I believe we'll get much "mileage" out of doing so (emphasis on "much").

      I suspect that once noobs with a problems get to the text-input box, everything except getting their plea for help published falls by the wayside.

      As to "enter title last," I'd hate to encourage that; what you're doing sounds to me like an expensive way of previewing your content.

      And did Valentine B. give you the money he owes me?

        Not that I (think I) have troubled the monks too much, but I consider entering the title when and only when, I'm reasonably satisfied with the content as a back stop - I have a (terrible) habit of hitting some combination of keys (probably just <CR>) that cause submission of the form far too early when I'm editing a new SoPW posting.

        P.S. Valentine B suggested you owed him ?!?! I'll put him right next time I see him (which is probably gong to be this time next year;-)

        A user level that continues to overstate my experience :-))
Re: RFC - How to ask...
by ELISHEVA (Prior) on Feb 15, 2009 at 06:12 UTC
    After just seeing (two) very long posts on SOPW, maybe we also want to add something lauding the glories of <readmore> tags? Something like:

    Please, be respectful of other seekers of wisdom. Very long posts make it hard for people to see questioners that came before you. If your question is very long (more than N screenfuls), start with a summary paragraph and include the details between <readmore> tags.

    For me, N > 2 (more than 2 screenfuls) is streching it and 4-5 is overboard. I suspect others have different feelings about when too much is too much, but I think coming up with some guideline of when a post is "too long" might avoid frustrating those who use the SOPW page.

    Best, beth

    Update: clarified "very long" - sort of

Re: RFC - How to ask...
by ww (Archbishop) on Feb 14, 2009 at 23:38 UTC
    Posted to How do I post a question effectively?, 2009-02-14, ca 1830 EST.

    All responses considered; many adopted! Thanks to everyone who helped.

    It's clear that more still deserve to be incorporated. And this quest is not over. Please keep the helpful comments coming.

Re: RFC - How to ask...
by Anonymous Monk on Feb 15, 2009 at 06:29 UTC
    Your font colors clash with some themes, so you need to specify background colors.
Re: RFC - How to ask...
by Lawliet (Curate) on Feb 16, 2009 at 22:06 UTC

    The updated version (as of 2009-02-15) seems shabby. This criticism doesn't really help, but I am not sure how to describe it. Are you trying to 'dumb it down' for the sake of the readers or something?

    Maybe it is the mixture of the different fonts sizes and boldness~

    Update: Perhaps the short version could be better organized, so that you do not have the clashing font sizes. Maybe remove the short version intro paragraph and have a fully documented example node.

    ## Example node - Text in parentheses are side notes from which the us +er is to learn <p>Hi all, I have a problem regarding blah blah blah. (Give relevant b +ackground information and briefly describe the problem.)</p> <p>I have read the documentation already (Make sure to link to the doc +umentation, if applicable. Also make sure that you read the documenta +tion, if applicable), but I am still having a bit of trouble. The pro +blematic code follows.</p> (Make sure that the code you post is relevant to the specific issue yo +u are having, and try to keep it short. Short enough to correctly rep +licate the problem, anyway.) <code> #!/usr/bin/perl # (The following two lines are important. No one will want to help you + if you do not have them. Keep that in mind.) use warnings; use strict; my $var = blah blah; print $var; </code> <p>As previously mentioned, the above code gives me an error:</p> <code> Can't locate object method "blah" via package "blah" (perhaps you forg +ot to load "blah"?) at test.pl line 7. </code> <p>Any and all help appreciated.</p>

    I realize that it is usually not as simple as that but I figure it is good enough to copy/paste into their node and edit appropriately (or something). I also realize that the example I gave should be vastly improved in terms of readability and correctness -- mine is just an example :P

    And you didn't even know bears could type.

Re: RFC - How to ask...
by Zen (Deacon) on Feb 16, 2009 at 21:13 UTC
    Too long. Anyone who reads this probably doesn't need it, or to be told "now you're getting close." Worries me how close the tone of this resembles linux forum sites. Are we all just angry and bitter folk? In any event, this and the markup need a quick reference. i.e. no editorializing and trying to be funny.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://743806]
Front-paged by Arunbear
help
Chatterbox?
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others avoiding work at the Monastery: (7)
As of 2017-12-14 19:44 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    What programming language do you hate the most?




















    Results (408 votes). Check out past polls.

    Notices?