The problem with all this is that even at the very core, the group of gods, this site is a distributed effort and very much a grown wilderness. Functionality has been added and some has also been abandoned over time, and content - even central content like FAQs and tutorials - is produced along the way by anyone who has the capability, time and mood to contribute.

And that's the problem right there, basically: the site is very community centered, more so than nearly anything else on the web. It's more of a wiki than a simple forum. That is the reason it is so confusing at first. Getting involved will not be an easy task for a newcomer, even given more documentation. I do agree that more documentation could and probably should be available, but offering it would be a bit like documenting which drawers in your room you put what stuff in - a lot of it is a matter of habit and some of ritual, so will necessarily seem obscure.

You simply have to take in the spirit of the site and its community for a while before it all makes sense the way it should - much like Perl itself can seem arcane at first, so does its community. Of course, that doesn't in any way constitute an excuse for insufficient documentation, but it does mean that just calling for "more documentation" is not going to change a whole lot.

Maybe any newcomers reading this would like to make a concerted effort of noting things down that confused them, or of things they found very valuable when they discovered them but which they had missed initially? That would help the more seasoned members provide answers on the one hand and pick out which parts are in particular need for documentation on the other.

As always, precise questions are more helpful to all parties involved than generic ones.

Makeshifts last the longest.

...this site is a distributed effort and very much a grown wilderness...

I assure, you that is all very well understood. No misapprehensions there.

...it would be a bit like documenting which drawers in your room you put what stuff in - a lot of it is a matter of habit and some of ritual, so will necessarily seem obscure.

Perhaps, but that's not a reason not to do it. I don't believe anyone would expect that the extra documentation I am asking for would be any less obsolescent than any other aspect of the site. I.e. no one has unrealistic expectations. But again, that's no reason not to do it.

...just calling for "more documentation" is not going to change a whole lot.

And that is not what I am doing. I am asking for specific items of information in specific places.

Maybe any newcomers reading this would like to make a concerted effort of noting things down that confused them...
As always, precise questions are more helpful to all parties involved than generic ones.

I believe that is what I have just done, thank you.

And the solution to the problem I have highlighted is not for me (or some other luser) to put together his own personal index of interesting nodes. Many users have done that, and they're all (perhaps not equally) obscure relative to the front page. Newcomers to the site need to have an obvious way to find out what the sections of the site are for.

All it would take is from someone with power to spend 15 minutes annotating the main sections which are not currently self-documented. The ones I'm aware of are:

1. The Monastery Gates
2. Seekers of Perl Wisdom
3. Meditations
4. Craft
5. Cool Uses for Perl
6. Perl Poetry
7. Obfuscated code
8. Quests
For some of these, the prose can simply be grabbed from elsewhere, e.g. from (OBE) What section should I put this in? and from The Perl Monks Guide to the Monastery.
...porque es dificil estar guapo y blanco.

> Maybe any newcomers reading this would like to make a concerted effort of noting things down that confused them, or of things they found very valuable when they discovered them but which they had missed initially?

Okay, here's one I found: Perl Monks FAQ seems to me to be exactly backwards. That is, I would rather have seen the general questions first, then the categories, and lastly the recent updates. When I first looked at it, it wasn't clear that the "next 15" link went with the recent updates as opposed to the categories. Reordering it would solve that too.

Just my $.02.

(FWIW, (OBE) The Perl Monks FAQ referred to by Oberon is now obsolete; the PerlMonks FAQ is the place to go; hopefully it doesn't have the same problems. ;-)

We're building the house of the future together.