Re: Documentation Improvement Proposal

On Aug 2, 2011, at 11:54 AM, Eric Hodel wrote:

> 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.
>=20
> 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?

Well, I prefer doing it in markdown to avoid the clutter of tags, =
converting to HTML using a tool of some sort. As for the layout part, I =
wish I were more familiar with how the documentation is generated. I'd =
like to improve on the overall style, but the best I can provide is a =
sample template with HTML, CSS, and JS showing how I think it should =
like. If someone can offer me guidance on how to integrate that into the =
generation workflow that would be great.

>=20
>> 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=

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

The out of sync part is I don't see where there's an easy to spot place =
on the documentation page that details the core syntax and details such =
as field input separators, blocks, yield, etc. It's the core API classes =
and the standard library, please a few links to books and what not, but =
those can become out of date. Take for example:

http://doc.ruby-lang.org/ja/1.9.2/doc/spec=3D2fcall.html

This is Japanese documentation explaining a few things such as yield and =
block arguments.

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

That's why I was suggestion moderation, it would help ensure that =
questions more suitable for -talk or IRC would not leak in. My general =
concern is that there would be interesting use cases which are not =
applicable to the average user. However after careful consideration I =
think these can be added as "articles" or put in a specific location for =
advanced use materials.

>=20
>> 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
>=20
> James Britt is the current maintainer of ruby-doc.org, you can contact =
him from his email address in the sidebar.

Okay I will give James a shout out.

>=20
>> * 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 )
>=20
> 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.

I will have to get in touch with them then. Just need to find the proper =
place to do so (some kind of chief contact that understands the project =
direction as a whole).=20

>=20
>>  * 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
>=20
> My recommendation is to stop proposing, stop asking and start doing.

I've already stated what I plan to do, it was more to get it out in the =
open and get people starting to talk about it. Consider it more of "Hey =
guys here's what I'm going to do" than a "What do you think about this?" =
Though I'm already getting back great feedback.

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

As I stated, work is already underway to translate the syntax portion of =
the JP docs (in fact I was working on it not even 10 minutes ago). Also =
I plan tonight/tomorrow to start putting the Koans into a tutorial style =
format. Yes, I totally plan to write a bunch of documentation.

>=20
> Through the challenge, documentation was increased from 54% to 65% and =
most of that increase came from outside contributors.
>=20
> See: =
http://blog.segment7.net/2011/05/09/ruby-1-9-3-documentation-challenge
>=20
> 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.
>=20
> 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.


As I mentioned I'll reach out to them (though I'll have to use formal =
Japanese, so it will take same time to write up). Partly because I'm =
curious of how the existing layout is built (static pages only, etc.).=20=


>=20
>> * Look at getting a project setup in redmine for people to file =
documentation bugs or any other issues that come up
>=20
> It's easy!  We don't need a new process for this!
>=20
> 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.

All right. I'll try and work out a patch a week to start out, then =
increase pace if it feels too slow. Mainly I want to get the content =
that doesn't exist yet up.

>=20
> You can also create a pull request on github but that may take longer =
to be applied.
>=20
>> I think this is enough to work with for now.=20
>=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
>=20
> (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`.)


That I will. Expect to hear from me soon :)

Best Regards,
Chris White
Twitter: http://www.twitter.com/cwgem=