According to DHH a Rails application does not need too much documentation. (check the post here)
He says if the naming convention is straightforward and the functions have average 4 lines of code every programmer will understand your code.
This sounds fairly nice, but if you are an average guy you’ll probably document your code.
Why you need documentation?
- Because after a break, when you’ll get back to development everything you have known before will disappear. We are feeding ourselves today with enormous amount of data and we have total breaks when our brain is simply reset to >null.
- Documenting your code is a DRY / refactoring process. You’ll re-arrange or move methods from modules, you’ll rename some functions, and you’ll optimize your source code visibility.
- You’ll add those missing tiny bits to your code which were skipped during the prototyping / development rush.
- Sooner or later you’ll open your code to others, and must provide guidelines of usage.
What are the characteristics of a proper documentation?
- It is generated!
- It is generated!
it is generated!
Many times the documentation is better than the code. You have the will to create something nice but the code won’t follow you.
And many times code and doc are not synchronized. To update a documentation is painful, needs the technical writer guy inside you.
What kind of documentation do you need?
- First you’ll have to have for yourself a good overview of your code. This is the Developer’s Guide.
- Then you’ll need a Specification of how your application works. This will be used together with your Customer to refine and extend your application.
- You’ll have to tell your users how they can use and benefit from your application. This is the User’s Guide.
Tools for documentation generation
- The most immediate is Rdoc. I could not find a proper usage guide so I was studying Rails source code. What I could not figure out is how in Rails’ RDoc the links are created. This is pretty bad, so I dropped RDoc in favor of:
- YARD Documentation Generator, which is built upon RDoc but extends with some nice features making the final result more readable. I’ve created a nicer skin to use, you can download here: YARD style.css Replace the old file in /usr/lib/ruby/gems/1.8/gems/yard-0.2.3/templates/default/fulldoc/html/ and all’s well. A screenshoot is attached for demo.
- RSpec is still the best tool for Specification and documentation creation.
- And finally, probably the tool which will merge all above into a nicer final document available as the User’s Guide, will be Gerbil.
