Beefy Boxes and Bandwidth Generously Provided by pair Networks
Come for the quick hacks, stay for the epiphanies.

Writeup Guidelines

by Tuna (Friar)
on Mar 12, 2001 at 22:16 UTC ( [id://63875] : monkdiscuss . print w/replies, xml ) Need Help??

Maybe it's me, but it seems like alot of posts to SoPW have been vague and/or ambiguous. After doing a search of this site, the only information regarding and writeup do's dont's is Writeup Formatting Tips , I want to ask a question of the Perl Monks; where do I start?. Now, possibly, if I did a more exhaustive search, I may come up with more reference to this topic, but I feel that this type of information should be contained directly in Perl Monks Site FAQ or Site How To. So, I decided to write a little something:

Seekers of Perl Wisdom Writeup Guidelines

Here are some basic guidelines for submitting a question to Seekers of Perl Wisdom:

  • First, and foremost, be able to articulate your question. Chances are, that if you can't, monks will not understand your problem and you won't get the answer(s) that you need.
  • Written "descriptions" of what you're trying to do, and what problems you are running into will rarely suffice, without accompanying code. Don't be bashful! Post what you have - as "ugly" or "wrong" as it might be. No one will persecute you for trying to figure out a problem on your own!
  • Which brings me to the next point: PLEASE, don't post a question, like, "I want a program that will do XYZ, then mail the output to ABC, and write it to a file. How can I write it?....". Chances are if you post a question like that, you will be downvoted, or altogether ignored.
  • Read Writing Formatting Tips before actually posting code. As you write your post, you will always have the option to preview your post. Exersise that option =).
  • Use Super Search to search for possible answers to your question. As this is a large, and active community here, there is a good chance that your question has been answered before.
  • Read previous Seekers of Perl Wisdom posts for ideas on how to pose your question.
  • There is rarely (if ever) a need to post hundreds of lines of code to get an answer to your problem. If you feel the need to do that, step back for a minute, attempt to debug your program yourself (I assume that you are already using -w and use strict;. Post only the code which is pertinent to the specific problem you are having. If you're post is going to be lengthy, be considerate and use <READMORE> tags.
  • There are alot of online resources here; take the time to read through them.
  • Read through: Voting Guidelines (or 'How should I spend my votes?'). There are some helpful hints contained in this document.

My final suggestion is that you are not already, become a member of This is an extremely knowledgeable and helpful community we have.

Edit 2001-05-12 by tye to add a missing > that was preventing the subsequent </ul> from being parsed

Replies are listed 'Best First'.
Re: Writeup Guidelines
by footpad (Abbot) on Mar 12, 2001 at 22:50 UTC

    Good start. I would like to add:

    • When posting code or preformatted text, do *not* use <PRE> or <TT> tags. Use <CODE> tags instead.

    • Treat the other monks with respect. Don't waste their time and they won't waste yours.

    • Please take the time to read the friendly manual. There's a wealth of knowledge provided with your standard distribution. Use it. If you're not sure where to start, type this from your command line:

          % perldoc perldoc

    You might also check a few of the links in this post and in this thread for additional ideas and guidelines.

    Also, when composing lists of paragraphs, you might consider adding <P> tags to your <LI> content, as was done above and in my reply to that thread I mentioned. (I'm turning into a crotchety old hack and personally find that easier to read than bullet points that are crammed together.) YMMV, of course. :)


(kudra: also see 'before you post') Re: Writeup Guidelines
by kudra (Vicar) on Mar 12, 2001 at 23:35 UTC
    I've always considered Ovid's 'before you post' a good list of practices (don't get embarassed Ovid, we know I only like it because I'm a good example in it ;). Kidding aside, you might want to check out that list to add to your effort.
Re: Writeup Guidelines
by Masem (Monsignor) on Mar 12, 2001 at 22:52 UTC
    One of the things I've noticed (And I've only been around 3 weeks to PM, but long enough on 'net time), is that many of the SoPW posts of late that fit the above patterns have been Anonymous Monk or people that only signed up a hour ago. (That's not to say all posts of people in the above catagories are of poor quality for SoPW, of course.) This is very reministent of USENET circa 94-95, when Netscape brought the 'ease' of reading USENET to the unclued public, which made for a large increase in S/N because people did not just read and lurk, or looked for FAQ.

    On the problem with the 1-hr askers (that is, those that create the account just to get their question asked), maybe perhaps they should have to wait 2 or 3 days after they create their account before they can post a new SoPW or any other 'parent-less' node; they can reply all they want and use the CB to ask questions, but at least this will help clear up what are clearly FAQ and other previously answered questions.

    But that assumes there's no AM function -- I'm not being critical, but I don't see the point of AM for PM, at least, I know how a AC is supposed to work on /. barring trolls and the like, as it's to protect the poster, but what is the harm in posting and replying with perl information, save in some cases like Node 451, such that it needs the AnonymousMonk function? Maybe perhaps AM's should be limited from posting 'parent-less' nodes as well, or have some filter which can analyze the question outside of the CODE and attempt to point the poster to previous replies on that same subject, priot to submitting the post? Or maybe there needs to be hugh honkin', BLINK'ed text that says, prior to entering the question, to use the FAQ and Super Search to determine if the question has been asked before. The guidelines for posting should be very much highlighted to the anonymous user as to avoid lowering the S/N for front-page nodes.

    Dr. Michael K. Neylon - || "You've left the lens cap of your mind on again, Pinky" - The Brain
      Another idea for the Anonymous Monk function: Perhaps only registered users of a certain level can post as Anonymous Monk. Or this in combination with any number of the other things you've mentioned.

      I personally like the AM, because it makes us a warmer friendlier place. Without it, we'd end up with a ton of throwaway accounts I bet. Unless we imposed a Wait Period, in which case our New Monk flow would slow to a trickle. I've tried a lot of other sites with discussion boards where you're supposed to get quick answers. I've never seen them work unfortunatly. The fact that you can have a reliable answer in 10 minutes here (or instantly in CB) probably keeps a lot of new guys coming back enough to join us.


        Maybe it's just me, but I don't see any reason for a "named" user to be able to post anonymously. That would only encourage hiding behind AM to avoid downvotes.

(Guildenstern) Re: Writeup Guidelines
by Guildenstern (Deacon) on Mar 12, 2001 at 22:21 UTC
    And always remember to close your lists! :)

    Negaterd character class uber alles!
Re: Writeup Guidelines
by toadi (Chaplain) on Mar 13, 2001 at 14:05 UTC
    Just wanted to add something more:
    1. First do %man perl
      Here you'll see the different perl manuals you can read.
    2. Second do what footpad told you. Do %man perldoc
      Learn this command! You can get information about perlfunctions, commands,... Just like the supersearch on PM.
    3. Last but not least. Don't trust all the resources on the web. Hence Matt's script archive :)
    So the best advise is. Try it first on your own. What you can get on perlmonks is: or a general direction how you can solve something or a solution of a problem you stumbled across when programming something. But don't expect complete out of the box solutions!

    My opinions may have changed,
    but not the fact that I am right

Re: Writeup Guidelines
by dmckee (Scribe) on Mar 14, 2001 at 15:32 UTC
    Why post as anonymous monk when asking Qs? You won't get a notice-of-reply in your /msg box...

    Another hint: make sure you put a relevant title. Not Can you help me or A small problem but Bizarre mod::perl behaviour or So what's this use strict thing, anyway, making sure that if someone comes along with the same question, that they'll hopefully hit it in the search engine.

    Perhaps first-time noders (ie: immediately after first-login) should be shown a page with FAQ type materials...

Re: Writeup Guidelines
by danger (Priest) on Mar 14, 2001 at 23:07 UTC

    Excellent post Tuna. There is also Ovid's before you post ... with a focus on reducing a problem prior to posting, and my own On asking for help which is long, but neglects to discuss any write-up formatting issues. Now, if we could just get all these (and perhaps any others I am neglecting) compiled in a single 'first time' faq and linked to from the Perl Monks Site FAQ or Site How to that would be a good thing. Though it may just be wishful thinking that it would help, as it is plainly obvious that many newcomers do not read the site faq (which has write-up formatting tips right at the top) and learn about code-tags after their first post.