Re: RFC - How to ask...

[ELISHEVA]

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

[ww]

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?"

[ELISHEVA]

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