Rant Re Rev Documentation

[Dan Shafer]

Not too far off the mark, Timothy, but a little.

When I started my Rev book "series" the idea was that i would simply  
"port" my HT book to Rev and be done with it. A number of users on  
the list at that time ensured me that if I did that, I'd be doing the  
community a huge service. It seemed like a pretty simple undertaking  
so I jumped in.

Boy, was I wrong. Not only would a port have been impossible (thanks  
in large part to the vastly richer vocabulary and power of Rev) and  
unhelpful, it would have been counter-productive. I couldn't bring  
myself to do that. So I ended up with a HUGE project and what I felt  
was a public commitment to produce it. I dug in and did the best I  
could under the circumstances. A lot of folks have kindly said good  
things about what I did produce and I'm continuing to add to the  
repertoire but it'll never be what's really needed.

As I look back, I think the better course would have been to write an  
intro to Rev and Transcript. As it is, my book is ONLY about  
Transcript, not really about how to build things in Rev. That's a big  
missing piece. I could write it but I just don't know if there's a  
market for it. Frankly, total demand for the first volume was  
surprisingly small (to me, not to Rev, but then they knew the numbers  
and I had to guess).

Maybe what's needed now is a comprehensive dictionary of Transcript  
in hypertext form from the perspective of a developer, but I'm not  
even sure how to start building something like that and feel pretty  
sure I'd end up getting slammed for "regurgitating the docs" if I did.

I'm just about to release my eBooklet on printing. What other  
subjects do people want? Is a thorough overview of the IDE really  
needed at this point? I gave one at RevCon West (well, not thorough;  
not enough time) but not a lot of people seem interested.

Sorry for the ramble/rant. Just trying to figure out what's most  
important to do next, if anything. There are days I think I should  
just shut up and go back to coding.


On Jul 24, 2005, at 7:22 PM, Timothy Miller wrote:

> I sometimes wonder why Dan didn't start by writing a comprehensive  
> reference. As I think about it, that's probably a no-win  
> proposition for an author, because Rev's free onboard documentation  
> would be a hard act to follow, even if it's not that good. And as  
> soon as Rev improved its onboard documentation, the book would stop  
> selling. I'd guess that's Dan's reasoning, but it's only a guess.



~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Dan Shafer, Revolution Consultant and Author
http://www.shafermedia.com
Get my book, "Revolution: Software at the Speed of Thought"
 From http://www.revolutionpros.com, Click "My Stuff"