On Sun, 20 Aug 2006, James Britt wrote:
> I've started a document on Writely.
>
> People can post comments and suggestions to this list; I'll update the Writely
> doc. Anyone interested in editing that doc, please send me your e-mail
> address and I'll add you as a collaborator.
I've just done my first set of edits. I've fixed a few typos, added
a little info to clarify things, but the most drastic change is that
I've added a paragraph at the start about the goal of the
guidelines. This is hopefully not controversial, but will help us
shape the document as it grows.
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.
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.
Hugh
|
