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

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??
While the information in the above article is useful, it comes off as a lecture. In general people don't react well to "shoulds". In particular people who should be doing specific things are likely to being told that outright. Therefore I recommend a somewhat different tone.

For an example of how to do that, here is a rewrite that shows what I mean. While I am making the same points, in the same order, I believe that this rewrite is more likely to inspire people to follow the good advice.


Here is a list of suggestions of how to improve your chances of success when you ask a question. Some of these suggestions are likely to let you answer your own problem. Others will help ensure a useful response.

  1. Use the -w flag.
    As is pointed out in use warnings vs. perl -w, this turns on optional error messages. This will often identify real problems much faster than we can.
  2. Use strict
    strict.pm turns on various useful restrictions. These are admittedly a bit of a pain at first, but experience suggests that it is well worth it for anything over about 20 lines or so. The nicest thing that it does is catch many frustrating and confusing typos in variable names.
  3. Use diagnostics
    Many of the error messages that Perl gives can be confusing. What diagnostics does is add explanations to the error messages. These explanations are less confusing and often include an educated guess at how to fix your problem. (This information is also available if you type, "perldoc perldiag".)
  4. Explain "not working"
    When something doesn't work there are generally many things that could be wrong and we have no way to guess at the problem without some information to narrow it down. So it is very good if you can give us as much as you can to work with. Typically that includes a description of what you were doing, any error messages, anything you can find in a log file (for CGI scripts this is likely to be the server log and its location depends on your webserver configuration), and so on. Without this we can only guess.
  5. Say what you tried
    This gives us context. Without it the best we can do is assume that you tried nothing and start with the most basic and obvious stuff. If you have tried it, you probably don't want to hear, "Is the server plugged in? Is it turned on? Is Apache running? Can you ping the machine?" But if you don't tell us that you can reach the machine and Apache is running, it may be the best advice we can give. So tell us that up front and you will save everyone some frustration. (As a side benefit people generally prefer answering questions when they have some evidence that the asker is giving it an honest effort.)
  6. Describe your environment
    Take a look at the output of "perl -v" for an example of what is useful here. The more we know about your situation, the better the chance that it will click with the right tidbit that we need to give an answer. For instance the fact you are behind a firewall makes a world of difference if you have trouble doing an ftp download. Being on Windows makes a huge difference if your question involves fork.
  7. Did you check CPAN?
    CPAN is a vast collection of modules and other code from Perl programmers around the world. Very often you can find a solution to your problem which has been tested and debugged there far more easily than you could write it for yourself. Even if you don't find something that does exactly what you want right now, you often will find a solution for another problem, you have or will have to solve. Plus just studying the approaches and code of other people is a great way to learn more about how to use Perl.
  8. Please use CGI
    If you are writing CGI applications, you should be using CGI.pm. The CGI protocol is deceptively simple. While it is easy to hand-roll code that sort of works for a while, it is generally a very bad idea to even try. See use CGI or die; for details.
  9. Show us the code
    Everything you can do to reduce how much we need to guess will improve our chances at providing a good answer.
  10. Show us sample data
    Knowing what your code breaks on is really useful. If your download breaks on a site, give us the URL. If your database loading routine is failing, show us what it works on and what it fails on. Don't make it excessive, but a small sample of what you are working with often makes a world of difference in how helpful we can be.
  11. Write clearly
    Please try to use proper grammar, punctuation, and spelling. When you don't do that, the message that we get is that you don't care to put any energy into communicating with us. If you don't think it worth communicating with us, why should we communicate with you?

    This isn't a test. After all many people here don't speak English as a first language. We try to be forgiving. But if you can make a good impression, try to.

  12. CGI is complex
    CGI scripts have their own set of challenges and when they go wrong do not provide as much (useful) feedback as you want. Most of the time you can get more useful messages if you try to run it from the command line. Likewise using CGI::Carp's ':fatalsToBrowser' you can get useful error messages out. And it is a very good idea to run through the points in The Idiot's Guide To Solving CGI Problems. The tone is regrettable, but the information is solid and will turn many problems into past headaches.
  13. Keep it appropriate
    This site is fairly specifically for people who are trying to learn more about Perl. We are not here to answer questions about other languages, or for doing your homework. Moreover we are likely to get annoyed if you ask us to do that.

UPDATE
Thanks to myocom for suggesting that I say CGI.pm at one point rather than CGI. I also fixed the omission of a blurb on CPAN.


In reply to Re (tilly) 1: How to get the most of your question from the monks by tilly
in thread How to get the most of your question from the monks by petdance

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others scrutinizing the Monastery: (15)
    As of 2014-09-23 16:47 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      How do you remember the number of days in each month?











      Results (232 votes), past polls