Beefy Boxes and Bandwidth Generously Provided by pair Networks
We don't bite newbies here... much

One Section to rule them all.

by benn (Vicar)
on Jun 16, 2003 at 13:46 UTC ( [id://266180]=monkdiscuss: print w/replies, xml ) Need Help??

A little while ago, I started a very small discussion about the Code Catacombs. I was attempting to make a point about organisation, but either expressed it badly, or nobody cared :) So I'm going to stick my neck out now (rather than waiting 'till next year as promised) and expand it all the way.

The more I look at *all* of the bits of code in the Monastery, the more frustrated my innner librarian becomes. This place is second only to CPAN as a resource for perlies, but it's such hard work finding what you need! Sorting the bits you need from the mass of code fragments lying around here takes a *lot* of Super Searching and reading.

I'm sure even experienced monks have difficulty deciding whether something is a small enough for a Snippet, cool enough for a CUFP, crafty enough for Craft or should just be plonked in the Code Catacombs. Even Where Do I Post X? is slightly confused on this - there is no mention of CUFP other than in a 2-year old reply suggesting it should be added (and for some reason, error with CGI program: Can't locate object method "connect" via package "DBI" is appearing as a child node - looks like a misplaced SOPW) - and it seems to me that the difference between Craft and the other two is simply based on the history of <code> tags.

The problem is that these are 'primary' categories. If you're trying the 'drill-down' approach to searching the Monastery for code, you have 4 main categories (cluttering, if I may say so, the main menu) to start off from, none of which are really intuitive or descriptive.

What's more, sections have different display and categorisation methods. Craft and CUFP are simply listed like question nodes, with no indexing, Code is categorised (but seems to involve editors manually placing code into categories as and when), and have additional desciption fields, while Snippets (which also have descriptions) are simply listed by title, along with a however-many-year old message about "When it gets to be more than one page, we'll categorise them" :) There's a brave attempt by grinder to index these, but that's not much use unless the snippets can be categorised by more than just name and title.

Add to this the amount of duplication and updating, and one realises why the some of the same questions get asked over and over, rather than the petitioner being able to simply find something that fits their needs. Many initial pieces of code, for instance, have been turned into CPAN modules - what remains in the Monastery may be historically important, but potentially confusing to somebody that finds the resource here first, especially if there's been a namespace change etc. and the original author hasn't updated the node or replaced with a 'Moved to CPAN' message.

Soooo.....I'm proposing a shake-up. One section to rule them all, one section to find them. Code Catacombs is already the most 'organised' of the lot, with descriptions, categories etc., so I suggest that *all* code should go in there. Posters of CUFP's and Craft generally stick a small description at the top of the code anyway, so there'd be no extra work involved in posting other than self-categorisation, and any of the editors (that have been freed of the responsibility of maintaining four different code sections) can suggest / amend this.

If it were felt that the 'previous' categorisations were important, they could be added to the description as an extra field ("Is this a snippet, CUFP or craft?"), but I think those categories would soon become redundant. They could maybe be added as Code sub-categories for now as somewhere to place the existing sections. Hopefully, with enough volunteers (see below), this 'backlog' could get cleared.

I also think that some resource needs then to be devoted to the organisation of the Catacombs. I won't repeat my previous ramblings, but they still apply. (OK - maybe not the thing about rep., but there should be *some* 'quality control' somewhere - even if only as a recommendation). Having a DMOZ approach, with lots of editors classifying and (dare I say) rating (after input from the monastery in the form of rep...{g}) would be very handy indeed.

If this were done, the Monastery would become more useful, useable and used place. I know it's a major job, and so I'm hereby volunteering myself (to whom, btw? editors? pmdev? gods? I get very confused...) to help with this particular Aegean Stable, and would urge others to do the same. Maybe if enough volunteered, we could have the job done by Christmas - a nice present to the Perl community.

I think my $0.02 have been well-and-truly spent now :)

Cheers, Ben.

<Readmore> and slight edit per author - dvergin 2003-06-16

Replies are listed 'Best First'.
Re: One Section to rule them all.
by rozallin (Curate) on Jun 16, 2003 at 15:44 UTC
    I agree, in principle, with this suggestion as far as the organisation is concerned, but not with the concept of making all code into one categorised section.

    I have always regarded Code Catacombs as a place for finished polished code; it performs a specific task, it is error free, and it has been, with the help of input from the Perlmonks community, tested and gone through perfective maintenance.

    Snippets, on the other hand, is a section for code that cannot stand as a program on its own, but performs a task or useful tasks that may be helpful to other users who are writing their own programs. As such, it should be kept seperate from Code Catacombs, but it should have better categorisation system than it currently has.

    The necessity of having both Craft and Cool Uses For Perl has always confused me though. I think Cool Uses For Perl should be made a subsection of Code Catacombs. Craft should be used as a temporary holding space for code that a monk wishes to submit for the Code Catacombs, but wants advice and feedback beforehand from others as to what could be done to make it an even better program before it is submitted to the Code Catacombs, which, after all, is where your Craft would really shine. Craft wouldn't need a categorisation system because it is assumed that the code will be moved by the user or by a moderator to Code Catacombs - in a sense it would be like a Seekers of Perl Wisdom for code.

    I also think that it would be a good idea to provide a small description at the front page of each of these sections to explain what each of these sections are about, and seeing as we already have a Super Search feature that can search in particular sections have a search box at the bottom of the page to allow quick searching of that section.

    I think this would make the Monastery a lot more useful as a resource for learners and programmers. And even if everyone else hates the ideas I have presented here :) I'd still be willing to volunteer as a NodeReOrganiser if the general consensus is that something does indeed need to be done about the organisation of code.

    Just my tuppence.

    rozallin j. thompson
    The Webmistress who doesn't hesitate to use strict;

      Well volunteered that Monk! :)

      I agree in principle about the difference between a 'snippet' and a 'program', but I think that this distinction is easily blurred - a well-crafted one-liner is a complete finished polished program, but would probably be placed in Snippets. Somebody looking to perform that task may never realise (or believe!) that a Snippet could do the whole job, and would be searching fruitlessly for a 50-line program. In a category listing, this could be indicated simply by a 'code class' field ("one-liner, snippet, module, program" etc.)

      As for the distinction between 'finished' and not...well, I don't know about you, but I've never finished a program in my life, after 20-odd years of coding :). Even the most 'perfect' of code in the Catacombs has comments, updates etc. - it all evolves. Again, a "status" field ("experimental,finished,mature" etc.) would solve this simply.

      Thanks for the comments,

        I agree in principle about the difference between a 'snippet' and a 'program', but I think that this distinction is easily blurred

        There was nothing in rozallin's proposal to stipulate that an entry in Code Catacombs had to be a particular minimum number of lines of code. If a one-liner stands on its own as a useful and reliable tool, then it would belong in the Catacombs. (Meanwhile, some "snippets" could be quite large, despite having limited utility...)

        I especially like rozallin's proposed distinction between the functions of "Craft" and "Catacombs" -- i.e. tentative vs. tested code. Note that rozallin used the term "polished", not "finished"; indeed, there is virtually no such thing as "finished" code (except for stuff that no one uses any more).

        And because folks can update their own root nodes in the Catacombs section, this is an excellent place to maintain useful tools.

Log In?

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: monkdiscuss [id://266180]
Approved by Corion
Front-paged by broquaint
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others taking refuge in the Monastery: (3)
As of 2024-04-21 17:48 GMT
Find Nodes?
    Voting Booth?

    No recent polls found