http://qs321.pair.com?node_id=946259

RFC. First Draft of proposed, shortform, guide to posting SOPW. Cuts, refs, negatives (but, yes, we all know that some people won't read guidance, no matter how brief) welcomed!

5 Jan update: Reviewing Marto's suggestion, below, and the ++'s -- which in this case, I read as agreement -- how say ye to adding (as I've done below) li 7? Or do you lean to Eliya's view?   I've also replaced the "Ditto" in li 3. Also, reordered to keep code questions together.


So, you're gonna' post a SOPW? Unneeded in last-second checklist. Stricken 5 Jan

Here's a brief checklist for your question.
  1. Code tags ( <c> ... </c> ) tags around data and code?
  2. Includes a tiny snippet of (compilable) code that reproduces/illustrates your problem?
  3. Narrative description (not "doesn't work") of how that code falls short of your needs or expectations?
  4. Also provides sample data?
  5. Quoted, verbatim, all error messages and warnings (again, inside code tags!)?
  6. A title that identifies your topic (and no, that doesn't mean "Help, please" or a module name alone)?
  7. Post your OS, Perl (perl -v) and module (if relevant) versions?
Here's some additional reference material:
On asking for help   |   How do I post a question effectively?
I know what I mean. Why don't you?   |   Markup in the Monastery

... and read the formatting tips around the the text-input and preview-edit boxes!

See luis.roca's Re: RFC - shortform posting guidance for newcomers.

Replies are listed 'Best First'.
Re: RFC - shortform posting guidance for newcomers
by luis.roca (Deacon) on Jan 05, 2012 at 15:45 UTC

    Right now the list (as originally posted) is fourteen lines without counting blank spaces and assuming no wrapping on the numbered points. That's too long. You could probably combine numbers 1-3 into, at most, 2 points. Each point could also stand to be shortened in length. You don't need the extra emphasis on any words and should probably simply linkify each point to one of the nodes it corresponds to listed at the end. (Similar to what was done on number six).

    Something like the following:

      SoPW Checklist:
    1. Did you clearly describe your problem?
    2. Did you use <code> ... </code> tags and check your markup?
    3. Did you include any warnings or messages your code returns?
    4. Do you have a clear title that is specific to your question?

    That said I think all this boils down to is wrapping someone's knuckles before they have even had a chance to raise their hand. IMO the best way to learn how to write a well formatted question on PerlMonks is to hang around for a while and see what is considered good or bad form. That's not a luxury everyone has. There are people who come because they're stuck and need help with a solution — today. They come, ask a poorly formatted question, get the usual replies with a list of links like above then simply move on to another forum/mail list. If they really understand their question THAT well and knew how to go about looking for answers, there would be no need for a SoPW at all. When someone asks a question, most of the time, they have little clue what they're doing. If you don't think they've asked it well enough — ignore it.

    As has been said, many will ignore the list so who is this for? If it's for people who are considerate enough to look through the site and try to adhere by our rules then I think it runs the risk of chasing them away. Personally those are the kind of people I would like to stick around — don't you?

    But even risking losing a few decent potential members, if this list only did one thing I will support it wholeheartedly: It eliminates the small parade of replies to poorly written questions that include the obligatory list of "How do I/How not to/RTFM" links. If it does that, go ahead and post it anywhere you like. :-)

    An even shorter list:

    • If someone blatantly ignores your rules of courtesy when asking a question, you can blatantly ignore them. ;-)


    "...the adversities born of well-placed thoughts should be considered mercies rather than misfortunes." — Don Quixote
      if this list only did one thing I will support it wholeheartedly: It eliminates the small parade of replies to poorly written questions that include the obligatory list of "How do I/How not to/RTFM" links. If it does that, go ahead and post it anywhere you like. :-)

      This is very much the wrong way to try to solve that problem.

      I sometimes vote down such boilerplate noise. Such usually reveals to me that no shortage of people have voted it up. Of course you get more of that stuff if people are constantly voting it up! You don't have to vote it down. But if you don't like it, then you should consider voting it down or /msg'ing the author, especially when the author is a "serial offender".

      My suggestion is for people to refrain from posting purely "you suck at posting questions" replies, especially with any speed. If you actually have something interesting and/or useful to say, then go ahead and reply with that and, if you want to, also provide some advice / links on how to post a better question. If not, then please give other people who it would seem are better at understanding questions that you find hard to make enough sense of sufficient time to show up, find the node, and provide a response that does not consist of 100% noise (to "the rest of us").

      Heck, if you have something interesting and useful to add and some bozo has already posted a "purely RTFPostingHelp" response, you might want to respond to the noise with the interesting / useful information along with a sincere and thoughtful expression of how it would've been better had they waited for someone like you to come along and post a "combo" reply (I don't advocate responding to 100% noise by adding another 100%-noise response).

      - tye        

        I will mention the effectiveness tutorials at the end of my reply, if I'm answering the question in full and/or providing a solution.

        I try to refrain from replies consisting entirely of links to the effectiveness tutorials until after the question receives ~6 replies, or at least one that answers the question completely.

        Sometimes I'll omit mentioning the effectiveness tutorials if the OP is very new, and it appears it would be just another thing to overwhelm -- but usually by next week, if the OP wasn't scared annoyed away, another opportunity will present itself :)

        I think that works.

Re: RFC - shortform posting guidance for newcomers
by marto (Cardinal) on Jan 05, 2012 at 12:38 UTC

    I'd rephrase item 3 on your list, 'Ditto' may be confusing, since English isn't everyone's first language. In some cases the following information is helpful:

    • OS name/version
    • Perl version (perl -v)
    • Module version (if the problem relates to a specific module)
      In some cases the following information is helpful: ...

      Yes, but with the list getting longer, even fewer people are going to read it or follow its suggestions...

        I suggested the information is often helpful, they could be asked for as a 'one liner' rather than an individual bullet point for each:

        "Post your OS, Perl (perl -v) and module (if relevant) versions"

Re: RFC - shortform posting guidance for newcomers (meh)
by tye (Sage) on Jan 06, 2012 at 07:57 UTC

    Here is a format for such a suggestion that I find much easier to evaluate:

    Consider changing the "add your question" display area to include:

    (show your suggested content)

    In context, please consider changing from the current:




    Title: [ (box to enter title) ]
    Your question:
    Use:  <p> text here (a paragraph) </p>
    and:  <code> code here </code>
    to format your post; it's "PerlMonks-approved HTML":
    [
      (big box to enter node "HTML")
    ]

    [ ("preview" button) ]



    To:



    (put your replacement here)


    To be clear, I'm not at all sure what parts of the above you were hoping to replace.

    I'm pretty happy with this bit:


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

    The rest, most people don't even notice. But I also like the simple list of HTML escapes.

    Providing text for people to read has proven almost pointless for a large number of posters. The "two-lines showing example mark-up" just sinks in almost without even engaging your "read English" synapses. The stuff below the input box is going to be widely ignored. Putting any links before the input box is too disruptive to standard keyboard navigation, IMHO. Putting more than a very few lines of text before the input box is too disruptive to visual understanding, IMHO. Putting example mark-up inside the text box is dang hard to get right (for example, it will very often end up being left in).

    I think we'd probably have a more positive impact by just replacing the last of those three "pre" lines with a very terse but clear notice that "look just under this text-input area for much more help". Especially if that help immediately starts with visually obvious bits (like the list of HTML escapes).

    I find your wording mostly "tl;dr" and when I force myself to read it, it flows badly as a bullet list. Where you put bold means that if I try to skim I get really little of value: "tiny code how sample data verbatim identifies your topic".

    Several of the things you ask for I don't think are relevant often enough to even mention so prominently. The important bits, IMHO, are just:

    Basic formatting:

    <p> paragraphs go here </p> <c> code goes here also sample input also error messages or broken output also desired output </c>

    But I also don't see how to convey even that with enough: terseness, clarity, snappiness. Perhaps more like:

    How
    to
    write:
    <c>
      code goes here, as does:
      sample input, desired output,
      errors, and broken output
    </c>
    <p>
      paragraphs go here
    </p>
    
    Important help information is just below this input box.

    I actually find the below-box text much easier to improve:



    - tye        

      I suspect it's difficult to view this from the point of view of someone like me, but references to HTML are, to me, part of the problem rather than part of the solution. It took me years to understand the point of the paragraph tags. The text was improved dramatically some time ago, but even now, the phrase "PerlMonks-approved HTML" is one I find daunting.

      I'm not here to learn HTML. I don't want to learn it as I have no use for it. I want to learn Perl, and that's hard enough. I've learned a little HTML because Pod2RTF doesn't produce a file that MessWord can read. The only other thing accountants (me and my audience) are likely to read is a web page, and since Pod2HTML is buggy, I've had to investigate the issues and find workarounds. Even that is a yak I'd rather not shave, so when I see "PerlMonks-approved HTML", it looks to me as though I must learn HTML and then the PM version of it in which I may have to unlearn some of the HTML I just learned. I really want to avoid shaving those yaks.

      I would therefore suggest cutting down the current guidelines to something along the lines of "Posts are HTML formatted. If you want to know more about this, see Perl Monks Approved HTML tags. Otherwise, " followed by the current text on code & paragraph tags. But the huge body of text on HTML that follows it makes my eyes glaze over even now.

      I accept that I'm hardly a typical user and that huge amounts of Perl are used in combination with HTML. But, to me at least, the heavy stress on HTML makes asking questions here less approachable.

      Regards,

      John Davies

        I can understand an unwillingness to unnecessarily learn yet another (whatever) when one's interests (and demands on one's time) lie elsewhere.

        But, note "unnecessarily" (emphasis added).

        I would argue that PM (and other forums where the ideas/specifics of the content are not readily communicated without fairly extensive markup options) make learning a minimal subset of html "necessary."

        And for an illustrated look at what and how markup works here, please see Markup in the Monastery. My guess is that a 5 to 10 minute once-over will show you all you need here, and most of what you need if accountancy goes out of favor, and actually writing html is (again) in demand.

        And + + for the suggestion that reducing the advice around the text-input box might be useful.

      tye:

      No argument; my wording -- as originally posted and still, as revised -- sucks compared to Luis.Roca's (at Re: RFC - shortform posting guidance for newcomers which is much better. Maybe the existing language is best.

      But (yep, clarifying info here) I'm still thinking in terms of forcing newcomers to see (and sure, some incorrigibles may just click thru) the advice either before getting to the text entry box or at the preview phase.

      If at the preview phase, it seems to me we could automate a test (are there any code tags? para tags). If the previewed text fails the test, then our code could automatically spit out the relevant guidance (such as "Use <p> around narrative </p>"). That's something done by many commercial sites which require (validate) entries. That doesn't seem to stop commerce... and though that's commonly done with js, we do have (pure-Perl) alternate options, do we not?

      Objections (and answers):

      • The test, as sketched above, would fail in the case of a one-sentence reply where the lack of para tags makes no difference to the rendering.
        But this is an edge case, and if someone has to put para tags around that single sentence, perhaps they'll remember to do so when next they post something more complex.
      • Such a test would be hard to write.
        Disagree and believe I can do that. What I find hard -- and where I defer to those with stronger 'everything-fu' is how to retain the user's input for correction, without js.

      Finally, (I think I'm agreeing here), the below-box help needs help. It is "busy" but needs, in your words, "terseness, clarity, snappiness."

      Update - Note to protect the good Monks reputation: this was posted after Re^3: RFC - shortform posting guidance for newcomers (meh) and Re^4: RFC - shortform posting guidance for newcomers (meh) and is merely a very rough PofC:

      #!/usr/bin/perl use Modern::Perl; # test the content submitted for preview -- for code and para tags $/="#####"; # will be followed by addtl samples -- good and bad my $nopara = 0; my $nocode = 0; my $preview = <DATA>; # print $preview; my @preview = split /\n/, $preview; for $_(@preview) { # say "\t Ln14, \$_: $_"; if ( $_ =~ /!<p/) { $nopara++; } if ( $_ =~ /(<\/\s*br>)/ ) { # arguably, this could be a s/ +// rather than a warning say "\n\t Bad tag -- &quot;$1&quot; -- found in \n \t $_\n"; } if ( $_ =~ /!<(c.*).*[;}] <\/c$1>/) { $nocode++; say "\n\t Do you need code tags in \n\t $_?\n?"; } } if ($nopara == 0 ) { print "\n\t You don't have any &lt;p> paragraph tags &lt;/p> in yo +ur draft. Do you need some?\n"; } if ($nocode == 0 ) { print "\n\t You don't have a &lt;c> code tag pair &lt;/c> in your +draft. Is that correct?\n"; } print "\n\n @preview\n"; # imperfect, as a good <br> gets ignored, b +ut perfectable __DATA__ I wantz to know if i can do this</br> <c>my $foo = 'bar' if (bar == bar); cuz that would be really cool.<br> oh, also, would somebody teach me how to use your parlmenks markup? love, foobar ########

      Output:

      Bad tag -- &quot;</br>&quot; -- found in I wantz to know if i can do this</br> You don't have any &lt;p> paragraph tags &lt;/p> in your draf +t. Do you need some? You don't have a &lt;c> code tag pair &lt;/c> in your draft. +Is that correct? I wantz to know if i can do this</br> <c>my $foo = 'bar' if (bar == b +ar); cuz that would be really cool.<br> oh, also, would somebody tea +ch me how to use your parlmenks markup? love, foobar #####

      More to come, but please pile in (or "on" if that's your preference). :-)

        I think this <code></code> and <p></p> parser would be harder to implement than it seems (even keeping in mind your counter points). There are, as far as I have noticed, a fare share of questions that are of the: "I don't understand the difference between grep, map and foreach." written in paragraph form and peppered with keywords and/or small snippets of code. There is also the question of how do you parse out incorrect code/pseudo code.

        I do think a short reminder above the poster's displayed previewed text is a decent idea worth exploring. Currently we have: "If something looked unlike you expected it to you might need to check out Writeup Formatting Tips" below the preview displayed post. Maybe that's not clear enough? If, as has been mentioned, the points are terse, few and clearly displayed above the preview, it could be helpful.


        "...the adversities born of well-placed thoughts should be considered mercies rather than misfortunes." — Don Quixote
Re: RFC - shortform posting guidance for newcomers
by Xiong (Hermit) on Jan 08, 2012 at 01:40 UTC

    Okay, my two cents: Nothing will prevent people from posting questions poorly. However, we do not have to approve all the poorly-asked questions. I don't think the engine needs work; the engineers may want to shift attitudes. No sense approving a post, then complaining about it.

    It might be useful to send an automatic message of some kind to those whose poorly-written posts are not approved after a day. By that time, it's fair to say that nobody remains with the ability and desire to approve.

    Sorry, your post [help my perl script do not work] was not approved. You might like to check out [How do I post a question effectively?]
    I'm not the guy you kill, I'm the guy you buy. —Michael Clayton
Re: RFC - shortform posting guidance for newcomers
by Argel (Prior) on Jan 06, 2012 at 01:49 UTC
    Great idea, but the list in luis.roca's post is written/phrased much, much better.

    Elda Taluta; Sarks Sark; Ark Arks
    My deviantART gallery