Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl Monk, Perl Meditation

Do we need to get "in your face" about readmore-tags?

by sundialsvc4 (Abbot)
on Feb 13, 2012 at 15:56 UTC ( #953483=monkdiscuss: print w/replies, xml ) Need Help??

Every few days, it seems (including today...) we have someone who posts a huge glob of Perl code and says, in effect, “fix this for me.”

Okay, I can sympathize with the latter sentiment.   (Every time I go to Home Depot, I want to buy This Old House with its gang of experts; every time I burn a culinary creation, I want the “cooking-show version” of a stove...)   But, the gobs of perl code, unadorned by “readmore” tags ... that is a problem because it goes on and on and on.

When I was writing this post, I momentarily forgot if the correct word was readmore (it is...), and so I went looking for it in “Markup in the Monastery” and very nearly couldn’t find it!   It is not at the top of the section where you would expect it.   I daresay that you would never discover its existence at all, unless you had a full five minutes with nothing better to do than to read and to read and to read some more.   Hmmm...

Our instructions for how to correctly post things, while technically correct, are so wordy and long-winded that I daresay no one out there actually does read them, unless first and/or repeatedly chided to do so.   (Every tech writer knows that to a certain degree you have to cajole the reader to keep reading.)   Maybe we need to change some of our templates and nodes.   Ideas?   Thoughts?

  • Comment on Do we need to get "in your face" about readmore-tags?

Replies are listed 'Best First'.
Re: Do we need to get "in your face" about readmore-tags?
by davies (Parson) on Feb 13, 2012 at 23:55 UTC

    As I said in Re^2: RFC - shortform posting guidance for newcomers (meh), some of us not only don't speak HTML, but don't want to, having no use for it. The higher you raise the HTML bar, the more you will do to drive away people like me, who want to learn Perl but not HTML. However well anything had been formatted, I would not have read and understood it before posting Connecting to MySQL. Once some kind janitor added readmore tags, I saw that what I had done needed changing and what the change was. Since then, I've been able to do it for myself. But trying to work out what HTML is important is still beyond me.

    I had similar HTML problems in other early nodes. Re: Perlmonks, money & music was fixed by dvergin after I posted an editor request, not knowing enough even to write an <a> reference. In Re^5: Modifying an existing Excel file, I tried the same method and had the error of my ways pointed out to me. In all these cases I learned something that wasn't in my plan. The reason I learned them was that I could see (or it was clearly explained to me) why what I did originally was inconvenient for those whose help I wanted.

    Because the denizens of this site were so tolerant of my blunders, I have learned far more than I would otherwise. Because this approach has worked for me, I think it will work for others. I would not have read Markup in the Monastery before my early posts (did an earlier version exist? This one is dated 2008, well after I joined). I don't understand much of it now - back then, there would have been no chance.

    I therefore suggest that tolerance and janitor intervention is going to achieve more than documentation, however well written. And how many of us are professional technical writers? Unless we can cajole or pay for some, it is almost certain that documentation will be lacking in some respects. I think there are better ways to help posters write better nodes than striving for perfect documentation.


    John Davies

Re: Do we need to get "in your face" about readmore-tags?
by JavaFan (Canon) on Feb 13, 2012 at 17:22 UTC
    But what will readmore tags do? You now have two options: either aren't going to click on the "read more" link, and complain the OP didn't post code, or you do, and end up with the same blob of text you're now complaining about.

    I didn't read the blob of code of the posting being discussed. Had the OP use readmore tags, and had I not used to setting to unfold readmore tags automatically for me, I would have clicked, seen the blob of code, and then decided not to read it. I would have to do work to do the same thing I ended up doing now.

    The only way a readmore tag would have made a difference for you is if you would not have unfolded the text, and would have just moved on. Who benefits from that?

Re: Do we need to get "in your face" about readmore-tags?
by wrog (Friar) on Feb 14, 2012 at 06:52 UTC
    There does seem to be an art to posting Just the Right Amount of Code, i.e., the magical twenty lines that distill the problem down to its essence with not a single line wasted on irrelevant crap.

    Problem is, the same people who will be the best at this will also tend to be the ones who already knew the answer in the first place. Funny how that works.

      The people who are best don't "already knew the answer". It's simply that they are likely to find the answer they are seeking in the process of refactoring the code to show the issue in a succinct fashion. One reason we encourage such refactoring is exactly so the potential poster develops the skills to be able to focus on an issue and isolate the problem.

      True laziness is hard work
Re: Do we need to get "in your face" about readmore-tags?
by ww (Archbishop) on Feb 13, 2012 at 18:00 UTC
    ++, but only for being concerned and posting a cogent writeup.

    But not so as to the substance, that "readmore" is insufficiently emphasized in our docs; that you went looking " “Markup in the Monastery” and very nearly couldn’t find it! It is not at the top of the section where you would expect it."

    Do you consider exposition and illustration of <readmore>...</readmore> more important than the section on code? on links? on paragraphs?

    To paraphrase, you can please some of the Monks, some of the time... and all of the Monks, none of the time.

Re: Do we need to get "in your face" about readmore-tags?
by Erez (Priest) on Feb 14, 2012 at 12:06 UTC

    I don't believe in getting "in your face" at all. If a user thinks that posting 5 pages of stuff will assist others in helping him, that's his prerogative, and I can only hope that this user will eventually understand that this might not be the best way of encouraging others to help. (Same with titles. If someone thinks "HELP stupied noob question" is the perfect title for describing his problem, he should have the right to do that)

    In many ways, "read more" is "read less", I'm a fierce opponent of code folding, since I don't believe in hiding information. If sections of code are too verbose, or too confusing, they should be refactored rather than swept under the folding rag. If I post something under a readmore fold, a, I run the rist that others will not read it, and b, maybe it means I should've re-wrote that section in a more succint way.

    Code tags and formatting is important, IMO, since improper usage of these breaks the site and hampers the experience of others, not the case with readmore, and therefore, IMO, shouldn't be a case for editing posts

    Principle of Least Astonishment: Any language that doesn’t occasionally surprise the novice will pay for it by continually surprising the expert

      The main reason for using a readmore is for those people who either browse the front page or browse the sections where node contents are shown with the readmore content collapsed. That allows readers to get an overview of a node without being swamped by a huge wall of text. This is particularly effective for meditations where the body of the meditation is tucked away in a readmore with a brief introduction shown in the section view.

      There are many ways of using this site. readmore is designed to make it easy for people who browse using the section views, but doesn't make any significant difference for people who read threads (accessed using Recently Active Threads for example.

      True laziness is hard work
Re: Do we need to get "in your face" about readmore-tags?
by Anonymous Monk on Feb 14, 2012 at 22:49 UTC
    You know .. it makes the front page sometimes several feet long. And the tag really IS almost undocumented...

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: monkdiscuss [id://953483]
Approved by Corion
Front-paged by chrestomanci
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others pondering the Monastery: (7)
As of 2018-06-17 23:14 GMT
Find Nodes?
    Voting Booth?
    Should cpanminus be part of the standard Perl release?

    Results (107 votes). Check out past polls.