Re: Documentation guide (writely)

On Aug 30, 2006, at 12:41 AM, James Britt wrote:
> 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.

Yeah, some rake tasks in stdlib-doc could really simplify things.   
And if the process for compiling ruby and running it w/o installation  
can be nailed down, that can go in the Rakefile as well. That will  
take some time though.  Hey, as a really future thinking idea, how  
neat would it be if stdlib-doc even included some sort of sandbox for  
writing TestCases that can be used to determine behavior under both  
(or more) ruby versions.  No installation or direct calling of ruby  
necessary.

My plan is that this document will start as a by-hand process, then  
gradually shrink as more of the documented stuff gets turned into  
scripted tasks.  And with any luck, you'll be contributing  
documentation by the time it's over too :)
-Mat