Beefy Boxes and Bandwidth Generously Provided by pair Networks
laziness, impatience, and hubris
 
PerlMonks  

Re: Make Purpose of each Section clear

by Callum (Chaplain)
on Nov 09, 2002 at 18:40 UTC ( #211665=note: print w/replies, xml ) Need Help??


in reply to Make Purpose of each Section clear

I joined perlmonks about a week ago, and am only just becoming familiar with all the different elements of the site -- in part because I'm one of the lazy folks who never bothers to read the manual before trying to get something to work, only resorting to documentation when I've accepted that I can't trial-and-error what the pin-outs are. My comments here are just my opinion based on a week of being here.

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.

Replies are listed 'Best First'.
Re^2: Make Purpose of each Section clear
by Aristotle (Chancellor) on Nov 09, 2002 at 20:45 UTC

    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 What section should I put this in? and from The Perl Monks Guide to the Monastery.

      > 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, The Old 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.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://211665]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others chanting in the Monastery: (4)
As of 2022-05-21 13:43 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Do you prefer to work remotely?



    Results (76 votes). Check out past polls.

    Notices?