Talli, I've obviously been remiss in leaving you out of my CR griping. :)
Seriously, every time I've had to work on code that uses the CR I've come to dislike it even more. I agree that the functionality it provides is desireable, but this particular implementation definitely does not fall into the sweet spot between functionality and usability as far as I am concerned (YMMV). Better documentation of what's there would definitely help, but it's not going to eliminate the inconsistent patchwork of helper procs, the need for extra joins even for things that don't need to be versioned, the nightmare (IMHO) of debugging code that is partly auto-generated, etc etc.
To me, the entire package feels like it was overly ambitious at the start, was incomplete when aD dropped it, and then has been hacked on periodically to provide the functionality that various people needed.
If I was writing a new package, the only reason I would use the CR would be if I cared about my package being adopted by OpenACS. If I didn't mind it languishing in the dungeon of contrib, I would avoid the CR like the plague. Maybe I'd even take a stab at writing CR2, which might actually end up being usable.
Just my $0.02. I know *very* well that not everyone agrees with me. ;)
