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

[sundialsvc4]

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?

[davies]

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.

Regards,

John Davies

[JavaFan]

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?

[wrog]

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.

[GrandFather]

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.

[ww]

++, 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 "...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."

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.

[Erez]

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

[GrandFather]

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.

[Anonymous Monk]

You know .. it makes the front page sometimes several feet long. And the tag really IS almost undocumented...