[Catalyst] Advent calendar

[Dan Dascalescu]

>> I'd like to suggest hosting the Advent Calendar articles on the Catalyst
>> Wiki: http://dev.catalyst.perl.org/wiki/adventcalendararticles
>
> When you have a project with an internet presence, and you don't have time to
> do a proper job, you put up a wiki and hack it into doing what you want.

You also put up a wiki when you want to have up-to-date information.

Case in point:
http://www.catalystframework.org/calendar/2006/6

Imagine someone new to Catalyst who comes across that page. There's no
notification whatsoever about the current state of BindLex.

Another example: last night in #catalyst, a new user googled
"deployment" and came across
http://www.catalystframework.org/calendar/2005/17. There was no
indication about modern deployment alternatives (listed at
http://dev.catalyst.perl.org/wiki/deployment).

> When you have a bunch of web developers, and your project is web development,
> and you need something done that's really not wiki-ish at all, you _do it right_.

How is documentation not wiki-ish at all?

Time has proven that the CatalystAdvent application is just not
conducive to host up-to-date documentation. Whoever wrote the articles
just doesn't (have time to go back and) update them, and others don't
contribute, for a variety of reasons.

Here's the most frequent scenario of why someone checks the Advent
entries: they are new to that particular area of Catalyst. If they
stumble upon an obsolete article, or one with errors, will they go to
the trouble of figuring out how to update the entry (that's not listed
anywhere either, but, ironically, *is* listed on the wiki)? Will they
get SVN permissions, check out, patch, then commit? Probably not. All
these will be way over their PITA Threshold [1]. And those who do know
how to update the entry, rarely revisit them, and are too caught up
with larger projects to bother updating.

[1] http://wiki.dandascalescu.com/essays/pita-threshold

So yes, if we want to have a Catalyst history museum, CtalystAdvent rocks.

> If Advent sucks (yes, organization could be better, and markdown has its
> pros, as well as its cons that you seem to be ignoring),

1. MojoMojo supports POD.
2. We're talking about MultiMarkdown, which is what MojoMojo uses.
What are MultiMarkDown's cons that POD doesn't have?

> Schlepping it onto the wiki has its own set of problems,

Like? There's a lot of documentation on the wiki, and more gets added
every week, as opposed to every December.

> and isn't in itself a _solution_ to anything.

I honestly believe the wiki is a solution to each of the problems I
mentioned in my first post:
* obsoletion
* presentation/accessibility
* ease of collaboration
* ease of editing (markup format) - random example: try to set the
text of an external link in POD
* plus, searchability. The Catalyst wiki has built-in search
(incidentally not enabled ATM). CatalystAdvent has to be searched
through an external search engine with the site: operator. Which
brings us back to the second example above.

Best regards,
Dan