[Catalyst] How to help with the wiki migration?

[J. Shirley]

On Jan 23, 2008 10:51 AM, Nathan Waddell <arafeandur at gmail.com> wrote:

> Looks good.
>
> However, I have a few quick questions:
>
> What is the difference between a How To and a Tutorial?
>

A how to is a specific instructive piece of text.  Examples of this would
be, "How to use a controller base class".   A tutorial is a start-to-finish
accomplishment, such as writing the Book database.  Many of the advent
articles could be slightly remixed into tutorials, since they go over
everything from start to finish.


> What is the /1 and /2 under Tutorial supposed to represent?
>

Right now we only have one tutorial.  The idea is Tutorial/1 is page 1 of
the tutorial.  Feel free to suggest other changes, we may want to have a
named level in there, like Tutorial/Book/1, etc.


> Is the reference link supposed to work?
>

Not yet, we need to get DNS setup and I need to finish the docpages project
-- it's a straight static rendering of the POD in the manual into nice easy
to navigate (as in, it has a navigation structure) HTML pages.  You can
preview this at http://catsite.toeat.com/docs/Advanced_Catalyst_Topics.html


> Please understand that I'm not trying to be pedantic. I'm trying to
> get a better understanding of what this document is espousing. I'm
> also thinking that if we have the categories of How To and Tutorial,
> we need to more narrowly define which is which.
>

Please, be pedantic :)


>
> Off the top of my head, I'd say a How To describes how to accomplish a
> narrowly-defined task with a small set of components, while a Tutorial
> describes how to accomplish tasks that are broader in scope with a
> large number of components.
>

Bingo!


> However, you placed module names beneath /HowTo, so is the difference
> that a How To describes how to use a single module?
>

The idea is "How to use REST", etc, rather than just a single module.  It
may cover several modules (like the AmazonXSL howto).  This stuff is still
very fluid, and open to change though.  Please continue sharing your
thoughts.



>
> I think it's key to define this clearly in the Content Structure
> document before there are lots of these documents out there.
>

Right, for several reasons.  First, I think it will help people figure out
their niche as far as content writing and editing goes.  Also, moving
forward we will run into problems if we move around a lot of documents...
Bookmarks and search links will have to be kept in mind at that point.

Thanks for your help with this Nathan, it is appreciated.  Please keep the
thoughts coming.

-J
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.scsys.co.uk/pipermail/catalyst/attachments/20080123/da80d=
b5d/attachment.htm