Gluttonous: Documenting Rails

Documenting Rails

kev — Wed, 10 May 2006 14:52:00 -0400

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       "system@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…

Grab the source by following the directions at dev.rubyonrails.org.
Choose what documentation you want to write or improve.
Make sure someone else isn’t already working on it by checking at the documentation report.
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.
Make your change and generate the RDoc to proofread
Create a diff with svn diff > my_diff_file.diff
Attach your diff file to the ticket you created in step 3, and change the ticket title so that [PATCH] is at the front.
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.

"Documenting Rails" by Conor

Mon, 15 May 2006 10:37:55 -0400

Hullo,

You should check out my documentation project for Rails (well actually for any RDoc). I’ve been working on and off on it for a bit now. User annotations and searching:

http://rails.outertrack.com

I think this might help a lot with documentation like this. Have Rails users annotate the documentation and then roll some of the comments into the official documentation. I believe this is how the PHP project does it.

Drop me an email at conor . hunt AT gmail . com if you are interested.

"Documenting Rails" by Paul Stamatiou

Fri, 12 May 2006 12:32:40 -0400

Awesome site Kevin. I’ve just picked up the Agile Web Dev w/ Rails book and am planning on learning a bit over the summer. I’ve added your feed to my feedlounge account.

"Documenting Rails" by Kevin Clark

Thu, 11 May 2006 16:12:02 -0400

anon: 1,2 and 8 aren’t really full steps and 1 only needs to happen once. How would you suggest we automate the rest?

Frederick: I understand (and don’t fully disagree) but as it has been given to me (who is as reliant on the core as you are), docs like the ActsAsList example won’t be checked in.

"Documenting Rails" by anon

Thu, 11 May 2006 08:57:32 -0400

8 steps is too many for each submission. get a better way of submitting with some automation and you would have a better chance of getting submissions. automate more.

"Documenting Rails" by Frederick Ros

Thu, 11 May 2006 07:27:18 -0400

Well regarding the ActsAsList example (and you know why ;), I’ve to say that a lot of peole I work with consider the doc as being incompletes because when looking at the HTML page there’s nothing written down bellow the insert_at method …

"Documenting Rails" by observer

Wed, 10 May 2006 20:33:38 -0400

Well, Django has a documentation system which has a tutorial which is kept in step with the changing codebase.

I think Rails core documentation team should look into something like that. One other thing that I liked about them is that the “Django book” would be open-source..

something the rails community should consider. Students and Rails afficionados in poorer financial situation would appreciate it. Not everyone is making 100/hr doing rails programming ya know.

"Documenting Rails" by Kian

Wed, 10 May 2006 19:54:53 -0400

This is a great idea. I saw Josh Susser last night at the SF Ruby Meetup and he really inspired us to go for the doc.

Do you have any ideas about what sections of the API documentation really could use the most help?

"Documenting Rails" by Eric A.

Wed, 10 May 2006 18:22:32 -0400

Kevin, awesome write up. It has inspired me to do some documentation. I think it would be handy to make a list of the areas that need the most work. Im gonna get into this more tonight and tomorrow since I dont have class tomorrow, and this would be a good way to get into contributing code as well.

"Documenting Rails" by Kevin Clark

Wed, 10 May 2006 17:14:28 -0400

dudus: Awesome. You don’t need to be an expert, just willing to put in the time to get it right.

"Documenting Rails" by .dudus

Wed, 10 May 2006 17:07:59 -0400

This looks great. Not a rails expert but I may try to help

"Documenting Rails" by Piotr Usewicz

Wed, 10 May 2006 16:45:40 -0400

Great! Make it as good as PHP docs are!