Re: Brainstorming ideas how to improve Ruby's documentation

On Sun, Aug 7, 2011 at 7:52 PM, Alexey Petrushin <[e-mail]> wrote:
> Text itself is fine, but I agreed, RDoc output is ugly and unusable
>
> Why can't it be like this http://railsapi.com/doc/ruby-v1.9.2

we need a list of requirements as to what will make for a successful
documentation effort. I have been working off list on finding a
suitable domain name. While ruby-lang.org/en/docs/ would work, imho, a
site dedicated to updated documentation would be better.

I propose that one chance we have to one up the competition would be
to have the examples executable with a reset option.
I would be more than happy to integrate this into TryRuby (yes updates
are coming, that's a different thread).
In this manner you could literally play with with and modify the
example code in the documentation and reset it to see the original.

Would copying the perldocs style format and writing standard, just to
get this effort underway be sufficient? What do you all ( the ruby
community) not like about the perldocs? It seems like they have it
going on. I would focus primarily on a website with PDF output version
of the docs first and manpage style docs secondary.

What it sounds like what we really need is standardization in how
documentation is written. We programmers are use to the idea of Coding
Standards. Perhaps we now need a Technical Writing Standard for ruby
docs? I don't want to turn this into some ITIL inspired garbage, but
some sort of writing standard agreement would be helpful here.

Respectfully,
Andrew McElroy
http://TryRuby.org