Hugh Sasse wrote:
Now, I was wondering if it is worth putting links in to information
for beginners about CVS. Obviously turning this into a CVS tutorial
is inappropriate, but people who want to get involved will need to
know where to look for information about how to use CVS update, etc.
I'd be inclined to mention the "Pragmatic Version Control with CVS"
book as well: I think with the large role the Pragmatic Progammers
have had in our Ruby community this need not be confused with
commercial endorsement. I only raise that in case anyone thinks
that might be a problem.
I liked that book, though didn't learn as much as I had hoped. I have
no issue with listing it as a resource, but I'd prefer that there be
references to a good set of *free* resources.
(I'd also prefer that the doc not try to be too many things to too many
people, but that's often hard to sort out. I sort of assume that anyone
attempting to read Ruby or C, understand and verify behavior, and
document it, also has CVS skills. But I'd also like to reduce
artificial barriers to participation and eliminate goofy mistakes, such
as fetching the wrong branch or version of code, so a link to a good
intro CVS guide is a Good Thing. And I suspect that people have the
same thoughts on using diff, something I could use a good reference for
since, as a practical matter, I've had little use for in some time.
Maybe some scripts that just Do The Right Thing? A Ruby Doc'ers Rake Set?)
One more point that I'd like to raise somewhere: at present there is
no way to keep *internal* documentation with the code. Rdoc doesn't
provide a means to support it apart from turning off Rdoc processing
(which is fair enough, it wasn't a goal of the project), but if
there were a means to markup documentation as being internal would
this be a Bad Thing? The present guidelines are almost perjorative
about internal documentation. Is this simply because it will be
exposed to the general user, thus leading to breaking of
encapsulation, or does it have detrimental effects on code
maintenance? I'm wondering if Rdoc should support internal
documentation in the future? I'd have thought that details of
choice of algorithms, tradeoffs in design, etc would be useful for
future maintainers. For one thing, constraints change. Available
memory and processor speed changes since the 1980's are extreme
examples.
Interesting. Yeah, might be nice to have alternate doc versions; one
with the conventional API docs, and one with the developer narrative doc.
Is it not enough that one can just look at the source for these?
James
|
