I agree about the API docs.  There has been talk recently about
working on them, but there are some snags we need to get around (I
don't know that you've been privvy to those conversations or not but
if not you should be :)).

As an aside, I'm working on re-implementing RDoc using ruby_parser.
It's in very bad shape right now (transitioning from using RDoc's
CodeObjects stuff to ruby_parser), but you can monitor my work at
http://github.com/jeremymcanally/docr .

The basic plan is to get the parser/normalization stuff in place and
tested this week.  Then I'll try to put a really lightweight bin
script/library in front of it next week.  Most of the same code should
work in that part with minor modification.  Sometime in there I'll be
extracting the markup stuff from RDoc into its own gem/library so it's
more separated from the mainline DocR stuff.  I believe I along with
others have plans to hack in some additions to the markup to give it
some more powerful structures.

Hopefully when this is in decent shape, it will be a well-tested,
nicely implemented Ruby documentation tool.

--Jeremy

On Tue, Apr 8, 2008 at 11:37 AM, Dave Thomas <dave / pragprog.com> wrote:
>
>  On Apr 8, 2008, at 10:02 AM, Phillip Gawlowski wrote:
>
> > While I agree, that the project is responsible for its own documentation
> > ~ (its rather obvious, is it not?), the tools we have in the Ruby
> > community to create documentation are limited to RDoc, a rather hacky
> > solution (Correct me if I'm wrong, but Dave Thomas said as much),
> > intended as a stand-in until a more useful tool comes around.
> >
>
>  I said it's a hacky _implementation_. I believe the concept is just fine.
>
>
>
> > However, the gem didn't include the files in ./, only ./lib, much unlike
> > the RDoc task. I had to explicitly tell the gem, to include extra files.
> > I lost more than an hour to that. The outdated RubyGems documentation
> > didn't really help. Fortunately, I found other Rake tasks, and could
> > eliminate the problem.
> >
> > But it shouldn't be this way, and I have the feeling it is a shortcoming
> > of RDoc (maybe not, I haven't looked at RDoc itself, so my assessment of
> > the reason maybe wrong, but my point still stands).
> >
>
>  Sounds like a configuration issue with the gem, to me.
>
>
>
> > Also, that RDoc generates frames for usage isn't the ideal solution,
> > IMO, as it makes search difficult (via a browser's search, anyway).
> >
>
>  The frames are just one option. Have you looked at api.rubyonrails.com?
>
>
>
> > And AFAIK, RDoc cannot spit out PDFs, PostScript, or LaTeX, or something
> > other than ri. And that makes it unnecessarily difficult to generate
> > non-RDoc documentation without third party tools (and I don't really
> > want to learn Yet Another Tool that is not directly related to
> > increasing my productivity in writing Code (that's what I want to do,
> > not write comments or documentation).
> >
>
>  Actually, I have it generating all three, as well as plain text, chm, and
> our in-house PML markup.
>
>  I'm not defending RDoc. But I think that if the situation is to improve, it
> should be through informed discussion.
>
>  There are a couple of underlying issues. Firstly, much of the basic Ruby
> infrastructure is not well documented. Many standard libraries in the base
> distribution have minimal documentation, for example. Many gems are only
> minimally documented (for example, having just API-level documentation).
>
>  Second, there's no good place to go to see documentation.
>
>  I think we have the basis for a great set of documentation. What is needed
> now is for someone with vision to take the next step. It needn't be a big
> one. In the same way that the RubyGems initiative set down some simply
> packaging guidelines that we all follow, I think that someone could drive
> through the same for documentation. It needn't be more than a few
> conventions. For example, we are used to seeing README and INSTALL in the
> top-level of an application. Change Gems to include these by default. If it
> sees a HOWTO file, include that. If it sees GUIDE, do the same. These are
> just suggestions--someone needs to take ownership of this and flesh it out
> properly.
>
>  We have the API documentation nut cracked. We need to do the same for the
> non-API documentation. And, if we set the conventions in place now, the
> tools will be able to use them to build a raft of different styles of
> documentation sites.
>
>  I'm looking forward to it.
>
>
>
>  Dave
>
>



-- 
http://jeremymcanally.com/
http://entp.com

Read my books:
Ruby in Practice (http://manning.com/mcanally/)
My free Ruby e-book (http://humblelittlerubybook.com/)

Or, my blogs:
http://mrneighborly.com
http://rubyinpractice.com