Re: Documentation guide (writely)

Mat Schaffer wrote:
> 

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

Oh, it may be me that's wrong.  Whatever, I just wanted to be sure the 
guide was unambiguous on what code to get and how to get it.  (This is 
where a Rake task would be uber handy).

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

./configure --help

will clarify (somewhat) the options.  I usually only configure for the docs:

./configure --with-enable-docs

(I'm going by memory on that)

make
make test
make install

But the main point is that people writing docs have a running system 
that is built from the same code base they are attempting to document. 
Building it yourself is perhaps the best way to ensure that.

> 
>> (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!

Well, I don't know what other folks do, but I have assorted machines and 
some VMware instances (which, incidentally may be a good tool for people 
looking to build a Ruby instance in a "pure" state to ensure that the 
behavior they see is not influenced by additional libs or environment 
settings. Xen is good option, too.)  My WinXP box has 1.8.4++ or 
something goofy.  My production server has the 1.8.4 stable, though I'll 
eventually get around to building 1.8.5.    I have some version of YARV 
installed someplace as well.

The guide should probably just note that when checking behavior, run 
ruby -v to verify the version.   (If the cvs checkout was on the same 
machine with the running Ruby instance, then a Rake task could generate 
an E-mail body that included the cvs diff as well as the results of ruby 
-v.  Then you wouldn't have to think about running it, and others might 
spot discrepancies.)

I think that doc patches will only get accepted after one or more people 
verify the content, so this is more for the people doing the docs to 
save them from wasting time.  (And, well, the time of people verifying 
the docs.)

> 
>> 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'll defer to Eric or Ryan on that.

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

I think the process has been pretty much based on assumptions and 
personal communication, and to the extent it can be made more explicit 
the easier it becomes for more people to add more docs more quickly.

I've never written any Ruby lib documentation, and part of that (in 
addition to the time factor) may have been some puzzlement over just how 
to get the correct files, format the comments, and produce a suitable 
diff.  None of that is especially hard, but for lazy people like me any 
barrier is a brick wall.

James