Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change
 
PerlMonks  

Re: RFC - shortform posting guidance for newcomers (meh)

by tye (Cardinal)
on Jan 06, 2012 at 07:57 UTC ( #946547=note: print w/ replies, xml ) Need Help??


in reply to RFC - shortform posting guidance for newcomers

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        


Comment on Re: RFC - shortform posting guidance for newcomers (meh)
Select or Download Code
Re^2: RFC - shortform posting guidance for newcomers (meh)
by ww (Bishop) on Jan 06, 2012 at 12:20 UTC
    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
        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 is also the question of how do you parse out incorrect code/pseudo code.

        Does that parser have to be complete and perfect? All we want at this point is a simple check that the raw posting text contains one or more <p> and zero or more <code> or <c> tags. (Tags, not elements. We don't even have to check for the closing tags. Existing code handles missing or mis-placed tags quite well.) Unless that condition is met, the poster will see a hint that (s)he should check is posting. Implementing those checks could be done using one or two simple regexps.

        Alexander

        --
        Today I will gladly share my knowledge and experience, for there are no sweeter words than "I told you so". ;-)
Re^2: RFC - shortform posting guidance for newcomers (meh)
by davies (Vicar) on Jan 07, 2012 at 18:18 UTC

    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.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://946547]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others exploiting the Monastery: (14)
As of 2014-07-10 22:38 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    When choosing user names for websites, I prefer to use:








    Results (217 votes), past polls