Beefy Boxes and Bandwidth Generously Provided by pair Networks
Problems? Is your data what you think it is?
 
PerlMonks  

Make Purpose of each Section clear

by jdporter (Canon)
on Nov 09, 2002 at 12:19 UTC ( #211637=monkdiscuss: print w/ replies, xml ) Need Help??

One of the things I found confusing when I started here was all those sections linked at the top of each page.

And unfortunately, just going to one of those pages doesn't (usually) offer immediate enlightenment.

There is a description of some sections at 'What section should I put this in?', but that node is not prominently displayed, and it's incomplete anyway, as it doesn't address "informational" sections of the site.

My suggestion is to have a comprehensively descriptive "table of contents" for the sections of the site, and also to have the main page of each section include its own description at the top.

I realize the information will be somewhat redundant, but there's nothing wrong with that. It should be understood that not everyone finds digging down several levels in obscurely named FAQ nodes to learn the purpose of the site's sections to be easy and convenient.

Thanks!

PS. I will, of course, be glad to offer my energies to this task, if there's a site guru with whom I can work on it.


Update

As a follow-up, I note that my request has been satisfied. Each section of the site now has a mini-doc at the top of its main page which explains the purpose/usage of the section. These docs are maintained by the SiteDocClan, so How is the PerlMonks FAQ maintained? applies to them as well.

We're building the house of the future together.

Comment on Make Purpose of each Section clear
Re: Make Purpose of each Section clear
by jdporter (Canon) on Nov 09, 2002 at 13:05 UTC
    Btw, this was not meant as a criticism; I know that as a site grows, certain luxuries can fall through the cracks.
    And yes, obviously some sections are well labeled/documented.
Re: Make Purpose of each Section clear
by Callum (Chaplain) on Nov 09, 2002 at 18:40 UTC
    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.

      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.

        > 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.

        ...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.

Re: Make Purpose of each Section clear
by fireartist (Chaplain) on Nov 11, 2002 at 16:29 UTC
    I agree that documentation for beginners could be improved, and I think that 2 minor changes would go a long way to improving things.
    • 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.
    Can we have some votes on these changes?
Re: Make Purpose of each Section clear
by jonnyfolk (Vicar) on Nov 13, 2002 at 19:05 UTC
    I don't mind the fact that everything's not immediately obvious. Time and curiosity will reveal most aspects of the site in the end. Somehow that seems like a metaphor for perl itself (or at least I hope so! :)).

    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.

Re: Make Purpose of each Section clear
by Acolyte (Hermit) on Nov 13, 2002 at 22:22 UTC

    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.

    Acolyte
    Studying at the feet of the masters.
Re: Make Purpose of each Section clear
by jdporter (Canon) on Nov 14, 2002 at 05:12 UTC

    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.
      > 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.

Re: Make Purpose of each Section clear
by richardX (Pilgrim) on Nov 15, 2002 at 02:30 UTC
    I love the work done so far++++

    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

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: monkdiscuss [id://211637]
Approved by BrowserUk
Front-paged by hsmyers
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others romping around the Monastery: (6)
As of 2014-09-20 11:08 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    How do you remember the number of days in each month?











    Results (158 votes), past polls