[Rake-devel] possibly helpful tweaks to the docs
jmg3000 at gmail.com
Thu Sep 7 15:30:06 EDT 2006
I'm just learning my way 'round Rake, and I'm grateful for the great
docs available. That said, here's my 2 cents on some small changes
that might be made to the docs at http://rake.rubyforge.org/ that I
think would make them even more helpful:
* Add "target" to doc/glossary.rdoc
* Possibly rename doc/rational.rdoc to doc/rationale.rdoc
* Not sure my guess is right here, but, in that rationale doc, add the
date it was written, and note at the top that the doc is historical
and many improvements have been made to Rake since then.
* doc/proto_rake.rdoc is a mostly empty page. You might either add the
code to it, or else remove it.
* in doc/rakefile.rdoc:
* Under "Tasks with Prerequisites", you might mention again that
prereq's are themselves tasks too. Also, I'm guessing the prereq's and
handled in the order they're listed (left-to-right) -- if that's the
case, you might explicitly say so here.
* Also under Tasks, you might tell the reader about the default
task, and how they'd know what the default task for their rakefile
*is* (and how they'd set the default task).
* The 2nd paragraph under "Importing Dependencies" may be
difficult to understand. You might change that first sentence to
"Because your dependency files will be already loaded...". Also, you
might change '"ready to go"' to "already generated", and also
sub!(/make/, "makes") in that paragraph.
* In the "Comments" section, you might add a line in the "rake -T"
output sample that contains the text from the "desc" command you just
* Namespaces section, first sentence can do without the "if".
* FileTasks subsection: sub!(/file task names in name space/,
"file task names in a namespace")
More information about the Rake-devel