| Subject: | Remove References to Old/New Ways of Doing Things |
First of all, the documentation is quite good.
But to a new user, the extensive discussions on new and old ways of
doing things can be decidedly confusing.
For example:
In Catalyst::Manual::Tutorial::02_CatalystBasics: Section "HELLO WORLD"
Show quoted text
> "The Simplest Way" reads as follows:
The ":Path :Args(0)" after the method name are attributes which
determine which URLs will be dispatched to this method. (Depending on
your version of Catalyst, it used to say "Private" but using that with
'default' or 'index' is currently deprecated.)
The entire statement in perentheses is irrelevant to a first-time user.
This is, after all, a tutorial on basics. An experienced user oughtn't
come to the Basics Tutorial to find something like this out, there
should be a place where he/she can go to find that out.
Another example:
Catalyst::Manual::Tutorial::03_MoreCatalystBasics: Section "DATABASE
ACCESS WITH DBIx::Class" > "Create Static DBIx::Class Schema Files"
This has a section on "load_classes" used by old versions of
Catalyst::Model::DBIC::Schema.
This section doesn't need to be here. You've made sure very clearly at
the beginning that you need a certain version of the module. Once you've
made that assumption, you don't need to have a discussion on what
happens if you don't have that version of the module.
This note can probably stay, but as a link to another page, perhaps. It
just makes an already lengthy document even more lengthy, while adding
no value to first-time readers, who will comprise the majority of
readers who are accessing this page.
Thanks very much. This is, on the whole, however, quite excellent
documentation.