On Aug 22, 2006, at 5:56 AM, Hugh Sasse wrote:
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.
I'm all for walkthrough-style stuff in this document. I'd like to
see this turn into a "Getting Started" type document as time goes on
with relevant links to things like learning CVS. But maybe we should
be more equal opportunity and link to a page that contains a number
of CVS resources (if there such a page) rather than just go straight
to the Pragmatic Book. Either way, I'm with you on that sentiment.
Thought I disagree with the placement of the paragraph. I'm thinking
the final document should be structured something like:
- Getting set up (tutorial style)
-- getting CVS copy
-- setting up stdlib doc and compiling docs
- Style guidelines
-- Where and how to write, indenting (bulleted lists)
- Submission guidelines
-- Where and how to post your changes (bulleted lists)
Lots of example terminal sessions, links to extra info, etc. And
probably a link near the top that skips to the guidelines sections
for people who just need a quick reference, maybe a table of contents
like thing.
I didn't quite get what you were saying about internal docs. But I
think I see now. I think it could be nice for rdoc to support some
sort of special marking as internal documentation that would be
hidden by default (similar to the show/hide source) thing. A place
for notes on tricky implementation. If that's what you're getting
at, I like it. But I'm not sure it's something we need to spend
energy on right away. For the time being, the show/hide source
function is probably good enough for most people. And we don't want
to implement it in a way that would encourage internal documentation
getting out of hand (usually a sign that refactoring is needed).
-Mat
|
