Robert, I agree however I'm relatively inexperienced with RDoc, and hear chat about how it's the conceptual stuff about cap that people struggle with; what runs locally, what do we mean by remote, deploy targets, roles etc..
I've even heard scary comments like "I'm thinking of switching from Rails to Capistrano" where people have become utterly confused.. there is the capistrano handbook, which I expect to replace the "getting started" on capify.org. I'll see what I can do regarding documentation, I may make some inroads with ApiDock and see what we can do, I may also start hosting the capistrano rdocs (which aren't bad) on the capify domain. - Lee 2009/5/21 S. Robert James <[email protected]> > > Documentation? The documentation I use for Capistrano is the source. > Even then, I need to use a lot of grep, since it's hard to know which > file really defines the underlying method. > > Capistrano is great, but, the documentation really suffers. If you > just want to use the standard recipes, it's easy enough. But, if you > want to make your own or change things, you need to grep the source. > > I would consider good documentation to be: > * Something like api.rubyonrails.com > * It should be generated from RDoc. > * Consisting of: > ** All of the included tasks. The description could be simply the > 'desc', and the source can be included in the HTML (just like RDoc) > for further details. The source is very clear. > ** All of the methods designed to be called from a deploy file. > That is, the RDoc doesn't need to show Capistrano internals, it does > need to show things like 'before' 'put' and 'run', along with all of > their options and perhaps an example. > ** All the vars that the standard tasks define. > > So, it seems like the key here is not writing more documentation, but > getting RDoc to work with Capistrano. Specifically: > * Being able to run RDoc (or similar) on a Capistrano recipe file. > * Being able to distinguish Capistrano methods designed to be called > directly from the recipe file, and RDoc those only, distinct from > Capistrano internals. > > I think getting RDoc or a similar tool to automate this is 100% the > way to go. > > > > On May 20, 11:41 am, Lee Hambley <[email protected]> wrote: > > I spotted this via my standing search for "capistrano" with google..... > I'd > > love to see how many people want to see better documentation, and > > suggestions for where we could strengthen things. > > > > - > > > http://rails.uservoice.com/pages/10012-rails/suggestions/98521-better... > > > > Do we need more documentation on any of the following? Core code, source > > modules, advanced stuff about user shells, user names, more resources > about > > keys, deprec, sprinkle, the list is endless, suggestions welcome. > > > > - Lee > > > --~--~---------~--~----~------------~-------~--~----~ To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/capistrano -~----------~----~----~----~------~----~------~--~---
