Beefy Boxes and Bandwidth Generously Provided by pair Networks
Syntactic Confectionery Delight
 
PerlMonks  

How To Ask A Question (Simple English) (RFC)

by Boldra (Deacon)
on Aug 14, 2009 at 09:55 UTC ( #788576=perlmeditation: print w/ replies, xml ) Need Help??

Standard English version of this node

Make your question better

Chatterbox
If you are a registered user, you can ask simple questions in the Chatterbox. Sometimes you can get a very quick answer. Keep Chatterbox questions short and simple.

Search
Before you post a new question, you should always search for old questions. Monks in the chatterbox can help you find the right words for your search. There is also an advanced search, called super search.

Other places to Search
You should check the Perl documentation. perldoc has documentation for the standard parts of Perl. CPAN has documentation for more modules. There's also Google code search

Title
After you search, use some of the same words in your title. Next time someone doing the same search will find your question first. Use a title that describes your question exactly. Don't use a title like 'Perl Problem' or 'Help!', they are very bad titles.

Perl
Perl will tell you more if you have "use strict; use warnings; use diagnostics;" in your code. Test your code yourself. Don't post untested code.

Explain your problem
Say what you want to do. Say what you tried. Show your code. Put your code in 'CODE' tags like this: <CODE>my $code;</CODE> . Don't post too much code. More than 20 lines is too much.

Show your error messages. Don't show too much. The first error is usually the most important error.

Check your question
Use the preview button. Read your question. Have you explained your problem? Is your English clear? Perlmonks does not format your question. Use <P> tags to make your question more readable. Use the preview button. Use code tags and the preview button again.

Patience
Beginner questions are usually answered in less than one hour. Answers take longer on weekends. Never post the same question twice. When you have an answer, read it very carefully. If you don't understand it, reply to the answer. Say "please use simple English". Read everything carefully and slowly.

Don't change your question after you post it. Use preview or post a comment on your own question.

Not all questions get moved to the Monastery Gates. Your question will get answered anyway.

Rules
Many of the rules here are the same as any web forum. Be polite. Don't make demands. Don't shout. Don't post personal information, email addresses or passwords. There are more rules in the Perlmonks FAQ

Environment and sample data
What input you are using? What does the output look like? What operating system? Does it matter? If you aren't sure, say it anyway.

Why strict and warnings?
Always use strict and warnings in your code. It helps you find possible errors. Don't remove strict and warnings to make warnings and errors go away. "use diagnostics" helps to understand the errors. If you still don't understand the messages, ask someone.

Bad Questions
Bad Questions can be seen in Worst Nodes. Why are they bad? Are you doing the same thing?

Getting better
If you are already doing everything here, look at some of the other nodes about posting questions, including How (not) to ask a question.


Background

This potential tutorial is specifically aimed at new monks who take one look at How (not) to ask a question and just give up, thinking "that's too long" or "I don't understand all that", and thus repeatedly ask bad questions. I don't assume the reader is an idiot, but I assume he is a beginner, has difficulty with English, and is impatient. The 'Simple English', in the title is intended to be attractive and not insulting for new monks. I'm also intentionally avoiding modal verbs, idioms and obscure vocab. I've left many qualifiers out, like 'unless' 'except when', and 'for beginners'. More experienced monks will know where they belong.

There are already many nodes about asking questions, but they are so long and full of links that they can be very daunting to someone who does not speak English well and is impatient (a nasty combination). I'm not trying to replace the older, wiser nodes, but act as a stepladder towards them. In particular, some new monks keep getting sent to How (not) to ask a question, which begins with a link to an outdated FAQ saying 'read this first'. The FAQ then links immediately to 9 other docs. Even a native English speaker could take most of a day to read all of that AND understand it. One of the goals in this node is to minimize such distractions.

I asked for feedback in the chatterbox. In line with my goal of keeping this really short, I decided against a section about 'please fix my mess for me' (rentacoder) kind of questions, because somehow I feel that monks just shouldn't get upset about this. Sometimes the lucky novice even gets the code they demanded. Instead I just added "don't make demands" after "be polite".

In line with chatterbox feedback, I scrapped the section on CPAN, to keep it to the point of 'read this before posting'.

Some form of this background comment will remain on the final version.

Comment on How To Ask A Question (Simple English) (RFC)
Re: How To Ask A Question (Simple English) (RFC)
by ELISHEVA (Prior) on Aug 14, 2009 at 13:21 UTC

    Awesome! and good work!

    Some suggestions:

    • Title: Wording suggestion (same idea. simpler sentence): Change
      Don't use a title like 'Perl Problem' or 'Help!', they are very bad titles.
      to
      Titles like 'Perl Problem' or 'Help!' are very bad titles
      .
    • Explain your problem: Error messages are very hard to read unless they are in <code> tags, so add something that says error messages should be also be put in <code>...my error message here ...</code> tags.
    • Check your question: Demonstrate how to use <p> tags and what they do. If someone needs to be told to use <p> tags they may not be confident about how to use them. No every Perl beginner is a web programmer. Maybe change
      Use <P> tags to make your question more readable.
      to
      Use <p>...my paragraph here ...</p> around each paragraph. Your paragraphs will look more like paragraphs.
    • Patience:Maybe add a paragraph (unless you think this is low priority and would make the HowTo too long):
      Do not blank out your question when you get an answer or even if you decide later it is silly. THERE ARE NO DUMB QUESTIONS. We keep a history of questions so your question can help others with the same question. If you blank it, we will put it back. If you want to "cancel" the question surround it with <strike>....</strike> and add a paragraph above or below to explain why.
    • Why strict and warnings? Either move to section just below Perl or merge with that section.

    Best, beth

Re: How To Ask A Question (Simple English) (RFC)
by ssandv (Hermit) on Aug 14, 2009 at 15:40 UTC

    This is a really, really nice summary of helpful stuff people should know. I have a few specific thoughts which may or may not be of use:

    • There's probably a middle ground between a strong warning against "rent-a-coder" type questions and having nothing at all in there. Something like...
      As with any online community, personalities vary. You'll usually get more, more effective help if it's clear that you've made a good faith attempt to do things yourself, and are stuck on a specific aspect of your problem, than if your question is very general or appears to require a lot more work on others' part than on yours.

    • It might be worth explicitly mentioning thanking people if you get help in the CB. That probably is covered by "be polite", though.

    • You could clarify the "first error is usually the most important" by adding a sentence explaining that often, subsequent errors are the result of the first one.

    • Explaining how to put code in the scratchpad wouldn't hurt either--sometimes the question is simple, but it requires more code than fits comfortably in the CB.
Re: How To Ask A Question (Simple English) (RFC)
by LanX (Canon) on Aug 15, 2009 at 00:54 UTC
Re: How To Ask A Question (Simple English) (RFC)
by toolic (Chancellor) on Aug 15, 2009 at 02:07 UTC
    Environment and sample data

    Please mention that sample input, output and error/warning messages should also be inside code tags. They are not just for code.

Re: How To Ask A Question (Simple English) (RFC)
by doom (Deacon) on Aug 15, 2009 at 03:56 UTC

    Not bad, but it's a little long to expect that the people who need to read it are actually going to read it. We were discussing the problem on the sf.pm list, and decided to try to keep it as brief as we could:
    how to ask perl questions

    Still, this node is much better than ESR's: Asking Questions the Smart Way

      I do agree with you that many people will not take the time to read it, in its current state. But I don't think that it is too long -- I just think it needs to be reorganized

      I would put a very concise bulleted list of the most important items at the top, and then go into more detail about each item below (and I would go into more detail on several of the items).

      Something like this --

    • Read the forum rules before you post -- take a look at the PerlMonks FAQ and the The Perl Monks Guide to the Monastery

    • Search before you ask -- Have you searched Google and used Super Search to try to find an answer?

    • Carefully explain your problem -- post your code, and any errors you are getting when attempting to run it

    • If your question is short and simple, use the chatterbox

    • Always use strict and warnings in the code you are posting

    • Preview your post -- check for errors and make sure you've provided all necessary information

    • Don't change your question after you post it. Post a comment on your own question

    • Be patient -- your question will get answered, we promise

    • -- should be at the top, followed by a more detailed section dedicated to each one.

      This way, people who are just scanning the rules will get the most important points before their attention wavers.

      Otherwise, this is an excellent guide -- good work!

      --jrtayloriv
Re: How To Ask A Question (Simple English) (RFC)
by apl (Monsignor) on Aug 16, 2009 at 12:57 UTC
    In the spirit of keeping it simple, I'd suggest replacing

    Perl
    Perl will tell you more if you have "use strict; use warnings; use diagnostics;" in your code.

    Why strict and warnings?
    Always use strict and warnings in your code. It helps you find possible errors. Don't remove strict and warnings to make warnings and errors go away. "use diagnostics" helps to understand the errors. If you still don't understand the messages, ask someone.

    with

    Perl
    Perl will tell you more if you have "use strict; use warnings; use diagnostics;" in your code. (See strict, warnings and diagnostics pragmas.)

    Feel free to use the explanatory node of your choice...

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://788576]
Approved by Corion
Front-paged by Jenda
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others studying the Monastery: (10)
As of 2014-08-21 13:20 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    The best computer themed movie is:











    Results (135 votes), past polls