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