[Catalyst-dev] RFC, docs reorg, again

[Matt S Trout]

On Sun, May 04, 2008 at 08:15:16AM +1000, Kieren Diment wrote:
> 
> On 4 May 2008, at 07:35, Matt S Trout wrote:
> 
> >On Sat, Apr 26, 2008 at 09:03:43PM +1000, Kieren Diment wrote:
> >>Please consider this idea:
> >>
> >>Ditch the Catalyst::Manual dist, move everhthing that's not the
> >>tutorial back into Catalyst::Devel, and make a separate
> >>Catalyst::Manual::Tutorial dist.
> >
> >Make it a Catalyst::Devel dependency if you like.
> >
> >-1 on rolling the thing back in unless somebody can show a genuine
> >advantage to it; "please consider this idea" doesn't count as a  
> >reason.
> >
> >
> 
> (Almost) Everyone with ::Devel installed needs the docs - but not  
> everyone with ::Devel installed needs the tutorial.
> 
> So we've got two independent dists here - the first are informational  
> pages (mostly pretty stable, Intro could do with a significant  
> rework) and the second is the somewhat out-of-date tutorial.
> 
> so a Catalyst::Manual dist, and a Catalyst::Manual::Tutorial dist is  
> what you're suggesting instead?

I'm not suggesting anything. I'm asking you to justify your suggestion.

> I'm just not completely sure of the  
> advantage of yet another dist, when Devel has a long release cycle  
> anyway, and the content of these pages is reasonably  tightly coupled  
> to the code.
> 
> ./Catalyst/Manual/About.pod
> ./Catalyst/Manual/Actions.pod
> ./Catalyst/Manual/Cookbook.pod
> ./Catalyst/Manual/DevelopmentProcess.pod
> ./Catalyst/Manual/ExtendingCatalyst.pod
> ./Catalyst/Manual/Internals.pod
> ./Catalyst/Manual/Intro.pod
> ./Catalyst/Manual/Plugins.pod
> ./Catalyst/Manual/WritingPlugins.pod
> 
> The second are tutorial pages (needs an overhaul - mainly ditching  
> HTML::Widget for FormFu or Formbuilder and using the new auth  
> framework API):
> 
> ./Catalyst/Manual/Tutorial/AdvancedCRUD.pod
> ./Catalyst/Manual/Tutorial/Appendices.pod
> ./Catalyst/Manual/Tutorial/Authentication.pod
> ./Catalyst/Manual/Tutorial/Authorization.pod
> ./Catalyst/Manual/Tutorial/BasicCRUD.pod
> ./Catalyst/Manual/Tutorial/CatalystBasics.pod
> ./Catalyst/Manual/Tutorial/Debugging.pod
> ./Catalyst/Manual/Tutorial/Intro.pod
> ./Catalyst/Manual/Tutorial/Testing.pod
> ./Catalyst/Manual/Tutorial.pod

So move Catalyst::Manual:: into devel and have a separate tutorial dist?

Could work but the reason we moved the damn thing out was complaints
from the documenters that doc releases were waiting for a release of a code
containing package (though that was -Runtime IIRC).

How about if we put all this crap off, and first work on getting a
docs -> HTML rendering that can live on the website done (I believe Jay
got most of the way to this). Then we can have the POD versions say very
clearly "we're a goddamn snapshot, here's the latest" and shifting them
back into a code dist ceases to be an issue.

Thoughts?

-- 
      Matt S Trout       Need help with your Catalyst or DBIx::Class project?
   Technical Director                    http://www.shadowcat.co.uk/catalyst/
 Shadowcat Systems Ltd.  Want a managed development or deployment platform?
http://chainsawblues.vox.com/            http://www.shadowcat.co.uk/servers/