In stumbling around the site I've found a couple of things that may be a little, if not confusing then at least counter-intuitive, to newbies. Information about the site is spread between several different locations, the major components of the site aren't obvious, and the 'user settings' page can be confusing.

If code should be self documenting, then so should a website -- I'm not at all advocating dumbing down, or denying that people should RTM before asking for help, rather that many peoples first instinct will be to try something first to see if they can intuit how it works, before RTMing. Would a simplified view of the site be viable? Anyone not logged in, or who hasn't selected a particular check-box on their user settings, or who dosn't meet some other criteria, sees a cut-down version of the site which highlights the elements likely to be of more interest/use to a newbie.

There is a lot of excellent information here, many exceptionally talented coders, and a lot of work has gone into building this community on both a technical and social level; though experienced users will be able to get full benefit out of this site, newcomers such as myself may find that there are a few hurdles to jump before we can find the wisdom we seek.

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.

• Change the Need Help?? link at the top of all pages to link directly to the Perl Monks FAQ node.
• As Oberon mentioned above, the Perl Monks FAQ page would read much better if it was flipped around into this order.
  • general questions,
  • then index,
  • then recent entries.

As one who doesn't believe in merely whinging when I could be doing something about it, I have drafted a page which I hope fills the need I describe above.

I humbly ask that all interested parties view my scratchpad to see the current draft, and give me feedback on how it can be improved, before I post it as a real node. no longer on scratchpad

Thanks, everyone...

That's good work! Perhaps one could combine this one with the guide to the monastery, and put a link to the node on every page.

O.k., I have finally submitted it as a new Tutorial. I'm not sure how to get to it, other than to go to Tutorials and scroll down to the "Tutorials written within the last week" section at the bottom.

Thanks, everyone, for all your advice and encouragement!

...porque es dificil estar guapo y blanco.

> I humbly ask that all interested parties view my scratchpad to see the current draft, and give me feedback on how it can be improved, before I post it as a real node.

I'd say that's quite excellent. There's several things there that I hadn't stumbled across yet, and I've been wandering around for over two weeks. I also like the formatting. I'd like to see that linked somewhere prominent.

I'll take a stab at this one as a relative newbie and web developer/architect...

It's true that from an information architecture standpoint the major links on this site are not always self explanatory. That is part of the site's charm though. Wandering through the nodes is much like browsing through heaps of scrolls in a lamasery (pun intended) searching for perls (sic) of wisdom. Having said that, there is one minor modification that I would suggest.

I'd include the Guide to the Monastery node in the main navigation at the top of the page. All the other items in the Information section of the sidebar are already included the main navigation or under the Need Help?? node. This link seems to be the only one lost in the shuffle. After a user is logged in it is only available by scrolling past the lengthy, but useful, Chatterbox and Other Users sections.

I believe this would also address the original issue here which is the availability of descriptions for each section in the site. The Guide to the Monastery nicely summarizes each section in one central place. A quick glance through the list would certainly be helpful for new users trying to make an educated decision about where to post.

Making all the information hyper accessible just speeds the pace up - dash in, dash out, finding out only what you think you need, not the information wiser monks think you ought to know.

I just get the feeling that perlmonks is a place you can wander round, taking your time, meeting people if you want, studying, browsing, all at a leisurely pace - rather like a gentlemen's club.

Shame there's no beer on tap, really!!

Write all that stuff if you want - I'm just happy to meander along finding stuff out on the way. This is a monastery, after all...

> I just get the feeling that perlmonks is a place you can wander round, taking your time, meeting people if you want, studying, browsing, all at a leisurely pace ...

Sure, I agree with all that. I've had a lovely time wandering around myself. But that doesn't mean we can't have little improvements here and there. We want to draw people in, to make them want to wander around. We don't want anyone to get frustrated trying to understand how things work.

At least that's the way I see it.

I would like to see a short version of "How to format text for posting questions" added to that. A quickie about how to use < code > and the like. I think this whole shebang should be emailed to each new member to Perlmonks when they register. Maybe even include a list of the most popular links to get them started.

Maybe title this whole effort "Perlmonk for Dummies" :}

Richard

There are three types of people in this world, those that can count and those that cannot. Anon