Posted by kev Wed, 10 May 2006 18:52:00 GMT
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:
+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 "firstname.lastname@example.org" # 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.