Re: Documentation guide (writely)

On Aug 29, 2006, at 6:22 PM, James Britt wrote:

> 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'm going off of what Eric said to work off HEAD and he'll back-port  
if the 1.8 change is trivial here.  Am I mistaken?

> 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.

Cool. I haven't tried to compile ruby yet fearing that it might be  
complicated and no-one's recommended it yet.  Do you know the build  
process?

> (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 seems like a border case to me, but maybe my single-computer  
view is skewed.  If there's something you think it should say about  
that, go for it!

> 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.

As above, I understood we were supposed to work on the HEAD.  Not  
sure if that qualifies as 1.9 or not from a terminology standpoint.

> 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).

Good point.  I'm think there should be stuff included in the setup  
docs to talk about testing the behavior of both branches before  
submission.

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

I was planning on verifying it, but my afternoon was pretty busy.   
I'll get to it at some point unless people beat me to it.

Of course, I'm sure a lot of people (most of you) on this list that  
know more about the process than I do.  I just got here so I'm  
writing from what I've discovered so far.  If there's something you  
think the document should have that isn't there, add it in, even just  
as a rough outline of a section.  Hopefully it will outline the  
process of discovery as I'm going through it so more people can help  
without this trial and error process.

-Mat