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).

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 ...
[download]

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.

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        

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.

Jenda


Support Denmark! Defend the free world!

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.

Missing a "problems" is indeed a problem.

:-)

Fixed with a "thank you!"

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();
[download]

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        

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.

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

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        

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

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 :-))

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

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.

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>
[download]

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