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
|
