Documenting Rails | How to document rails

[Pavan Agrawal @ Ruby On Rails]

As many of you know, the documentation for Rails is lacking in several
places. Several of us have taken it upon ourselves to clean things up
where we can and we're trying to make a push for the community to help
out.
Why write documentation?

There are several reasons why you might like to help with the
documentation process even if you're not a writer.
Writing about Rails makes you learn

Just as they say teaching makes you better at your subject, writing
about Rails will force you to learn about what you're documenting.
Cleaning up documentation for the core codebase means that next time
you'd like to tweak options for associations, or write that web API
you've always wanted, or fix that bug that's been driving you insane
for the last week you can.
It means when you need to look something up, it's there

Writing documentation is good for you! When you forget the options for
url_for you'd like there to be something to refresh your memory (this
happens to me too). If everyone chips in a little, we all get a lot
out of it. Additionally, when that new Rails developer on your team
just doesn't remember how ActionMailer works it'll be easy to point
them to the documentation when you know it exists and is readable.
It helps the community and just feels good

If you're reading my blog, it probably means you've got some stake in
Rails. For me, it's my day job. Rails is the reason I really enjoy my
work. Writing about it and making it easier for others to have the
same experience is really fulfilling for me. It's about giving back to
the group that helped me when I was starting with Rails.
Ok, I'm convinced. How can I help?

We'd really love for everyone to help with the documentation, but we
need to adhere to some style guidelines first to make sure that the
new docs are up to par and won't need to be rewritten.
Write to teach

Rails documentation is not an academic paper. The point is to describe
what a developer needs to know in order to use the section of the API
that you're writing for. For example, in my rewrite of the
ActionMailer documentation (here) I made sure to cover the basic
usages of ActionMailer as headings so someone can easily find what
they're looking for.
An example is worth 1000 non-example characters

Examples are key. Do say what the class is used for, but make it easy
on people who don't want to know about every facet of the render
method. Give them an example how to use the method as well and you'll
have happy coders.
Don't repeat yourself!

If we're working with the ActsAsList module and it has a method that
looks like insert_at(position = 1), you probably don't need to say
that the method inserts an item in the list at a position, defaulting
to 1.
Writing docs with RDoc

Rails documentation is generated by RDoc so you'll want to become
familiar with it. The Pragmatic Programmers have an excellent
explanation of how to use RDoc in Programming Ruby 2nd Edition and the
RDoc Documentation has a section dedicated to an example and markup.
The Rails documentation can also be used as a reference on how to
write RDoc. Please familiarize yourself with the basics and follow the
conventions you see in the Rails source.

The two things I use most often in documentation:

* <tt>something<tt> or +something+ are used to make text
typewriter style and should be used for method names
* An indented block will display as code. For example:

# Examples:
#
# class MyMailer < ActionMailer::Base
# # Set up properties
# # Properties can also be specified via accessor methods
# # (i.e. self.subject = "foo") and instance variables
(@subject = "foo").
# def signup_notification(recipient)
# recipients recipient.emailaddresswith_name
# subject "New account information"
# body "account" => recipient
# from "sys...@example.com"
# end
# end

Generating the RDoc to check your changes

Generating the RDoc for the project you're working in
(ActiveRecord,ActionPack,ActionMailer etc) can be done with the
command rake rdoc in the project directory. I have added an option to
the ActionPack Rakefile so that you can generate RDoc for select files
using rake rdoc DOC_FILES=FILE1,FILE2 this should probably be added to
ActiveRecord, but ActionMailer has so few files as it is that it
probably doesn't need it.

Please remember to look at the files RDoc will generate before turning
in a patch!
And finally, the quick version of the submission process...

1. Grab the source by following the directions at
dev.rubyonrails.org.
2. Choose what documentation you want to write or improve.
3. Make sure someone else isn't already working on it by checking
at the documentation report.
4. Create a ticket at the Rails Trac page describing the section
that needs cleanup and why. Make sure to add the 'docs' keyword to the
ticket.
5. Make your change and generate the RDoc to proofread
6. Create a diff with svn diff > my_diff_file.diff
7. Attach your diff file to the ticket you created in step 3, and
change the ticket title so that [PATCH] is at the front.
8. Watch your ticket (if you gave your email, you'll be notified
upon changes) and make changes if they're needed. If things go well
then you'll have your documentation in the core!

Go, do it!

That's all I've got. Lets make sure the Rails documentation is getting
progressively better. It's just The Right Thing.