Re: Documentation guide (writely)

Mat Schaffer wrote:
> I made some major changes to the document today to start moving it  
> toward the guide I see it as.  Just wanted to call attention to it so  
> that people could offer comment.  I'd like to flesh out the stdlib- doc 
> instructions more still and maybe reword some of the guidelines.   But 
> that will take some time.  I also need to test the command I  provided 
> for checking out the 1_8 branch.  I just got it from a CVS  tutorial.
> 
> I haven't published it yet, so I don't think anyone not associated  with 
> the writely document can view it.


Question:  The guide first show how to fetch the Ruby source using "co 
ruby", but then says to get the 1.8 branch, using "co ruby_1_8 ruby"

I also think that anyone doc'ing the code needs to have it compiled and 
running so that they can see that the code really does what the docs as 
are describing.  (The installed Ruby need not be on the same box one 
uses for editing the docs and creating the cvs diffs, but people 
claiming to know what the docs should or shouldn't be have to have 
first-hand experience with a running system someplace.)

This may seem like a big "Duh", but I'm wondering if this guide should 
be explicitly focused on improving docs for the current stable release. 
  Instructions and such should be worded so that people do not 
accidentally end up with Ruby 1.9.

I expect (I'm guessing, really) that most people interested in 
contributing doc patches are going to be folks running the current 
stable release and who find that existing docs do not match their 
experience with the actual code.   Something in the guide should explain 
that these are instructions for improving the *current* stable release, 
and that one must verify that the installation they are using as a 
reality check is the same code (and not, say, 1.8.4).

And all examples should ensure that cvs operations  work against the 
current stable release.

James