docs

[Devin Asay]

On Jan 16, 2008, at 11:56 PM, Peter Alcibiades wrote:

> "supercard docs leave the user reverse enginering for dollars"
>
> Yes. Yes, so true.
>
> The problem is not with the existing docs, which are just fine for  
> what they
> do.  The problem, for people learning it, is that they are like a  
> cookbook
> all about ingredients but with no recipes for dishes.  Its like  
> trying to
> find how to make apple pie from a book which has very fine informative
> entries for apple, pastry, sugar - but no entry for pie.
>
> What you need when you are learning however is a cookbook that  
> starts from
> tasks.  The great Carla Schroder's Linux Cookbook is a fine example.

Just to remind everyone--there is a fine "cookbook" of recipes  
included in the Rev documentation, albeit easily overlooked. Just  
open Documentation > Getting Started, then choose Sample Projects or  
Sample Scripts. This is not an exhaustive list, but does give a good  
taste of how things are done in Rev.

These recipes are also searchable using the Search feature of the  
Documentation (Thanks, Eric!) Search also lets you search the mail  
list archives and several key web sites maintained by Rev developers.  
The Search feature is under-promoted and so often overlooked. It has  
saved my bacon many times.
>
> By the time I have learned Rev properly, if I am spared that long,  
> I'll have
> personally written one in the form of notes on topics encountered  
> as problems
> to solve, and so will many of us.  It would be a great  
> collaborative project
> were something like this to be done right.  It would probably make a
> significant contribution to Rev's success and adoption if there  
> were one
> available.
>
> If everyone on the group just contributed one a month, it would be  
> a fantastic
> resource, and would grow to a respectable size very fast.  I'd be  
> happy to
> help.  Not with writing recipes  (which might be a bit of a  
> disaster) but
> with editing and so on.
>
> "Revolution Recipes".  It has a nice ring to it?

See comments above. :-)

Devin

Devin Asay
Humanities Technology and Research Support Center
Brigham Young University