Re: Documentation Improvement Proposal

On Aug 2, 2011, at 9:36 AM, Chris White wrote:
> [=85]
>=20
> So if a user wants to study Ruby's handling of numeric types, they can =
easily narrow down on them. Those interested in systems program can =
focus on the Operating Systems category. Finally, it helps when a user =
who has no idea what class to look for by narrowing down the list of =
choices. =46rom there the user can decide what class best suites their =
needs, and compare it to other similar classes.

Your focus seems to be largely on the HTML documentation, but there's =
also ri.  Why don't we take your proposed front matter and check it into =
ruby itself where both ri and any generated HTML can take advantage of =
it?

> Next is the language issue. Ruby is a programming language with roots =
in Japan. This means that a good amount of the core team speak Japanese =
as their main language, and I've noticed the Japanese documentation [2] =
to be a bit more thorough and better laid out. In fact there is already =
a project underway to improve the Japanese documentation[3]. However my =
fear is that the English documentation will become further out of sync.=20=


The documentation from the core standard library is written in English, =
so I'm uncertain about what will become out of sync between the two.  I =
think you're writing the wrong mailing list though, you should contact =
the rurema people to have your concerns addressed.

> As a final concern, both sets of documentation do not provide a way =
for the addition of user comments. This is a core feature of the PHP =
documentation that make it such a success. Users can point out weird =
edge cases or useful examples of how to utilize something that is not =
apparent by simply looking at the provided documentation.

Having user contributions only on a website seems like a waste of =
community effort.  User contributions should be aggressively curated to =
fold documentation improvements back in to the source material and =
remove bug reports and "how do I use this?" type questions.

> This are just a few issues with much more that I could go into. Now =
with that all in mind I'd like to discuss a proposal for improving the =
state of the documentation.
>=20
> =3D Steps Towards Improvement =3D
>=20
> So are the steps I would like to take in order to improve the overall =
status:
>=20
> * Find a hosting sponsor as an official documentation project will =
most likely generate a reasonable amount of traffic which would be too =
much of a financial burden for me to take on alone

James Britt is the current maintainer of ruby-doc.org, you can contact =
him from his email address in the sidebar.

> * Establish a content management system / wiki which will allow for:
>   * User comments
>   * Multiple contributors ( content writers, translators, editors, =
etc. )
>   * Multi-lingual support ( not just Japanese and English, but also =
allow for translations in multiple languages )

I suggest you get in touch with the rurema people before attempting to =
build something they don't want and won't use.  When I spoke to okkez at =
RubyKaigi about combining efforts I got the idea that this is not one of =
their goals and that they wouldn't want to use such a tool.  It may have =
been due to my lack of proper understanding though.

>   * Revision support for rollbacks and ability to see revision history
>   * Support for syntax highlighting
>   * Ability to categorize / tag / adjust navigation
> * I'll start putting up documentation, the idea being that I would =
like to have a good chunk of content up so everyone has something =
tangible to see
>   * Most likely I'll start by doing a port of the Ruby Koans [4] to a =
more tutorial oriented format, as I like way the content is categorized
>   * Continue my translation [5] of the Ruby Japanese documentation so =
that there is a reference of some type for parts of the language which =
are not classes
> * Once this is done I will put out a call for contributors including:
>    * Content writers
>    * Editors
>    * Translators ( while not essential at this phase, it would be nice =
to get it started early before the scale gets massive )
>    * Site administrators / moderators ( For helping to moderate =
comments and make sure they're not spam or are off topic )
>    * Anyone to add comments to help improve the general documentation

My recommendation is to stop proposing, stop asking and start doing.

I didn't ask if people wanted to contribute documentation to Ruby 1.9.3, =
I challenged them and gave them easy guidelines for contributing.  Then =
I wrote a bunch of documentation myself.

Through the challenge, documentation was increased from 54% to 65% and =
most of that increase came from outside contributors.

See: =
http://blog.segment7.net/2011/05/09/ruby-1-9-3-documentation-challenge

Similarly, rubygems.org was written by Nick Quaranto without asking for =
permission.  He simply did it and now we have an awesome site for =
hosting gems.

I'd still like to avoid duplicated effort between rurema, any =
improvements made to ruby-doc.org or a replacement of ruby-doc.org, it =
may be easier to build by simply fulfilling the needs you see are unmet.

> * Look at getting a project setup in redmine for people to file =
documentation bugs or any other issues that come up

It's easy!  We don't need a new process for this!

You create a patch and attach it to a ticket in redmine in the DOC =
category.  You can even assign it to me for faster commit.

You can also create a pull request on github but that may take longer to =
be applied.

> I think this is enough to work with for now.=20

Please, just do it, but if you add user comments please make it easy to =
fold them back into the source and remove them from the website.  If I =
were a PHP committer and found myself encountering a page like this I =
would be embarrassed at my failure to incorporate useful contributions =
by users: http://www.php.net/manual/en/function.openssl-sign.php

(Fortunately I wrote OpenSSL documentation for Ruby that contains =
examples similar to those provided in the user comments of the PHP site. =
 You can see it in Ruby 1.9.3-preview1 if you `ri OpenSSL`.)=