-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Dave Thomas 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.

Err, yes. I like the idea of RDoc myself. I like it very much, almost to
the level of fan boy. It is very easy to generate API docs. But that is
the only thing it can do, it seems.

| Sounds like a configuration issue with the gem, to me.

Yes, it was. I had to tell the gem specifically to find these extra
documents. My chip on my shoulder is, that this shouldn't be necessary,
especially when the RDoc task in my Rakefile actually generates the
documentation without declaring these documents explicitly.

|> 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?

Which is still a frameset. The layout's different, but that's it.

| 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.

Yes, of course. I'm not shouting to purge RDoc from the Rubyist's
toolkit, not at all. However, it stopped progressing at some point, and
no body has taken over to expand it.

(However, I have found a github repository that seems to tackle the
issue. And I'm waiting for the source code to take a look at it.)

| 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).

The hashing functions in the STDLIB have no documentation. Having looked
at the STDLIB documentation for Ruby in the past, I'm looking at the web
first, and spend my time tweaking search-engine queries, and find some
sort of tutorial on how to use it. Which makes me sad.

And since I'm not good at reading C, or other people's code just yet, I
can't contribute with documentation patches, and *that* makes me an
unhappy camper: Not being able to contribute in correcting issues I see,
and help out a great community. :/

| Second, there's no good place to go to see documentation.

Indeed. If there were, the Rails API wouldn't be on 5+ websites to look
at. Similar for Ruby's documentation. That it isn't very searchable is
another issue, IMO. (OTOH, neither is Javadoc from what I've seen. Well,
there's no silver bullet, is there?).

| 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.

To put my money where my mouth is, I'm willing to contribute to this
effort in any way I can. Be it coding, writing documentation, or
evangelizing it..

What I'd like to see, is something like RDoc, which grabs formatted
files (In Textile, Markaby, RDoc's variant,..), and emits documentation,
from files that are in some way specified (a .document extension, maybe.
Something that is convention over configuration, to make the transition
as easy as possible).

I think I can hack up a simple tool that demonstrates what I mean (after
all, there's RedCloth, and Rake's FileList to accomplish what I mean).

Once I have that running, I'm perfectly happy to hand it to anyone who's
more qualified than me to work on this tool.

| I'm looking forward to it.

So am I.

As a personal note: I did not mean to criticize you or your work, Dave.
In fact, if I could find my copy of the Pickaxe again, I'd drag it along
to have you sign it. It was a great help to me in picking up Ruby, and a
very valuable reference for the documentation. Thanks for the effort by
you and all who contributed to it. :)

And I'd go nuts without RDoc to generate API documentation.

- --
Phillip Gawlowski
Twitter: twitter.com/cynicalryan

~ - You know you've been hacking too long when...
...you "woke up" this morning and thought, "I'll checkpoint here, snooze
a bit more and then revert to checkpoint."  A while later you go up
another consciousness notch and realize that you hadn't checkpointed
successfully
~ - "Oh, of course.  I didn't have the keyboard."
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.8 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkf7lycACgkQbtAgaoJTgL8WjgCgkdQ+8JTKfPj3FoYllVffiVDs
DgkAn28WmpugQ/yH+LyqCpVDcZH0XUnp
=RXLi
-----END PGP SIGNATURE-----