Re: 2nd try at date/format.rb & pty.c

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