Welcome to the Monastery!

This node is being developed as a collaborative effort by Perl Monks to help people who may be unfamiliar with online forums in general, or sites based on the Everything engine which drives the site in particular. This is the 'Executive Summary' - for a more detailed version of this doc and its history click New Monks. New posters to Perl Monks may (in the fullness of time) be sent a link to here to provide a useful entry point to all things Monastery and Perl. This is our attempt to help newcomers get the most out of the monastery and a language we love.

We believe there are no stupid questions, so if you can't find an answer just ask.

1. Instant answers for common Perl problems

Perl Monks has its own extensive Question and Answer section which has a different focus from the standard Perl FAQ. Most common perl coding problems are addressed in these two documents, so if you need an answer yesterday...

4. Finding help

5. SuperSearch

Super Search is an online Perl Monks utility that allows you to comprehensively search the Monastery for answers.

6. Just who/what are Perl Monks?

Basically the Monks are a group of individuals from across the globe who share a common interest in Perl. All are welcome and experience levels range from novice to guru. Everyone gets a home node that they are free to decorate as they see fit. You may like to check out some of the home nodes of our resident gurus, they are as eclectic as Perl itself but contain a wealth of knowledge and experience. You will find them here: Saints in our Book.

Point 4, the "Please, please, please use the following"
suggests to use use diagnostics. While this can
be useful sometimes, it will never "find" any more (potential)
problems that use strict or -w will.

I stress people to use strictness and warnings. That will
help them prevent making mistakes. use diagnostics
doesn't belong in that class.

Not to be overly critical, but I really don't like that line. The "just stupid answers" part might discourage people from answering questions, or give them the impression that we're a bunch of jerks who aren't really funny. I personally can't think of an ending that I really like on it, though I would like some really funny catch phrase.

I would turn #4 into the following:

4. Please, please, please use the following

Study these these pragmas and try putting them in your code. They help pinpoint errors, and give explanations about what's wrong, and might even explain how to fix it.

use strict; is useful mostly because, like in C or Java, it forces you to declare all your variables before use. This eliminates errors from misspelled variables and encourages the programmer to structure his/her program clearly. It also prevents some tricky things with references and subroutines.

use warnings; (or almost equivalently the -w command line switch) and use diagnostics; are closely related pragmas. use warnings; detects a ton of non-fatal errors caused by syntax mistakes, context misperceptions, etc... use diagnostics; can usually tell you how to fix these problems. These two pragmas especially benifit those new to Perl who are not yet familiar with Perl's idiosyncracies.

Update: I would provide the basic definitions here because getting a new user to start reading Perl's massive amounts of not particularly intuitive documentation is asking quite a lot. Start them out slowly, while they're still feeling their way around.

-w is not actually equivalent to use warnings. The most obvious difference is that the warnings pragma is only available in perl5.6.0 and later.

The other, very important difference is that -w is global, while use warnings is lexical. -w will turn on warnings for all the code used by the script, including in other files. use warnings, on the other hand, will only enable warnings for the block in which it occurs. If you put use warnings in your main script, you won't get warnings from the modules that you use.

It is probably sufficient to recommend -w for new programmers; it works in all versions of Perl, and is the most general way of getting warnings.

The use or not use of strict module, depend at the platform
and class at,whould you programing the script.
For example :

If you write a native service, whith Perl Dev Kit, and use the module "perlsvc" you can't use strict module, but if you write a console program, you can use it.

Personality, I like use that 3 modules : strict, warnings and diagnostics, and make a simple "sub" called logdump, at that make a simple file whith all output, its simple remmember for first programmers.

As you note they were written: [ [ node ] ] Have changed to | format to avoid problems, which is consistent with the top format but not the [Reply]. It seemed to work fine for me. I presumed it would parse \[ [node] \] but have never looked to see.

Some of these comments are very picky... I worked as a text editor1 for some time. Your mileage may vary.

I would modify the first sentence to "...may be unfamiliar with online forums in general, or sites based on the Everything engine in particular." (I think the number of people completely ignorant of online forums who would actually find us is probably low, but there are various differences particular to this site.)

I agree that the "no stupid questions, just stupid answers" comes off wrong, but am at a loss how to correct it and keep the "feel".

In #3, I would reword to "PerlMonks has its own Questions and Answers section, which has a slightly different focus than the official Perl FAQ. Most common perl coding problems are addressed in these two Frequently Asked Questions documents." (one reason for this is to avoid the confusion of so many different FAQs -- thanks for not mentioning the Perl Monks Site FAQ, which would have sent this completely overboard. Also, a document doesn't "contain" a slant, it "has" one. I changed to "focus", since "slant" is often seen as a negative term.)

In #6, a tiny change: "...home nodes of our resident gurus. They are as eclectic..." and maybe add Outside Links to the extensive link lists.

I think I would move points 3 and 4 up to the top of the list - I guess they are what you want anyone to do first. I'm not sure about use diagnostics; versus use warnings; I suppose it all depends on your level.General comments:The document asks rather than demands.. which is the polite thing to do. But if the purpose is to reduce the number of posts that ask questions that have well-known answers, and to reduce the number of posts that don't provide sufficient info in the first instance - then perhaps the document should be more authoritative. Human nature being what it is - people will probably not look at all the recommended links, they will skim the document and then post. Maybe start with something along the lines of:Before posting ask yourself the following questions - is the question already covered in the FAQs? - am I using strict and warnings? - have I supplied enough code and data so that it is clear what I'm doing?etc...Each question would have the appropriate links - I'm sure that others more skilled in this sort of thing could improve the phrasing - the aim being to be authoritative and friendly/encouraging at the same time.
Update:Has the idea of having an example question and answer been discussed? The question would illustrate all the good practices discussed in the main document e.g. what was trying to be done, what happened, code snippet included, use of HTML tags etc. The answer would show the sort of helpful reply that you get back!*****Example:
I'm trying to count the number of times a file has a line with "foo" in it. The program looks like this:

This document rocks. I think it really embodies what perlmonks is to me.
In the interests of providing a snappy, concise document, I have some suggestions for the intro.

If you are an experienced Perl programmer who simply has not posted before, we apologise for inconveniencing you.

I'd strike this sentence. The document is very good info for experienced perl coders who happen to be new to perlmonks. Item #2 definitely shouldn't be apologized for.

If you are new to Perl you will often find the answer you seek is already available, so if you need it yesterday have a look through these links.

IMHO, strike this too. This is addressed in item #1 just below.

We believe there are no stupid questions, so if you can't find an answer just ask.

This is an *excellent* sentence. I would move this into item 3, for when the reader is thinking about asking questions.

And I would move the last two sentences to the end of the document, just before credits, otherwise we're saying goodbye to them in the middle of the document they're supposed to read all of.

With these changes, the document would flow like this:

-----------

Welcome to the Monastery!

This node is being developed as a collaborative effort by Perl Monks to help people who may be unfamiliar with online forums in general, or sites based on the Everything engine which drives the site in particular. This is the 'Executive Summary' - for a more detailed version of this doc and its history click New Monks. New posters to Perl Monks may (in the fullness of time) be sent a link to here to provide a useful entry point to all things Monastery and Perl. This is our attempt to help newcomers get the most out of the monastery and a language we love.

1. Instant answers for common Perl problems

Perl Monks has its own extensive Question and Answer section which has a different focus from the standard Perl FAQ. Most common perl coding problems are addressed in these two documents.

Thanks to all who have contributed to date. All suggestions incorporated where possible whilst still keeping base doc short. I am writing a new node on the benefits of strict, warnings and diagnostics to provide a user friendly intro to their benefits, avoid the man pages, and give somewhere to link. Initial draft should be up for discussion in a few hours.