I’ve been reading and writing some Python and Elixir code lately. It’s gotten me thinking about how documentation is treated in code bases. In those languages, documentation is a first-class citizen. In Ruby and Rails, not so much. We rely on self-documenting code and robust test suites to explain the code’s intent to humans. self-documenting code and robust test suites are important, but I’ve been wondering lately if they’re sufficient means of explaining what our software does, especially to newcomers to a project.
I also spend a lot of time working on a large, legacy Rails application. The other day I was removing some outdated code from it, and realized that the generated HTML docs in doc/app weren’t in sync with the code. They were so out-of-date that, when I regenerated them, the new docs used a whole new theme. We had updated the app’s Rails version more frequently than we’d generated its docs!
That’s a shame, for at least a couple of reasons:
Now I’m working on improving documentation for my Rails projects, and in the process have been thinking a lot about my approach to documenting Rails applications in general.
Below are the practices I’ve been working on to build reliable documentation for my Rails projects.
Your application’s README is still its gateway, the first thing new developers will likely read when they access its source code. If your app’s README consists of the default given to every new Rails app, it’s time to change it.
Your README should include:
bundle install. For example, if I need to to install Redis or ImageMagick to work on the app, or configure environment variables to talk to external services, let me know up front.
rake doc:app, but as we’ve already covered, we’ve gotten pretty good at forgetting that step, as Rails developers.
The HTML version of your Rails docs will need to be regenerated regularly, in order to keep up with the code they explain. I am finding that ignoring the doc/app directory makes sure that stale documentation doesn’t stick around from commit to commit, and just makes commits cleaner in general. This is why it’s important to mention how to generate the docs in your README–they won’t be easily accessible, otherwise.
There are a handful of documentation generators available for Rails apps, but I’ve stuck with the default RDoc for projects I’m currently documenting. It does the job, and I can always swap it out later if I need something more robust. No sense in overthinking it in the meantime. That said, if you already have a preferred documentation gem, then by all means, use it!
So, what do you document in a Rails application, then? I looked to the command line output from running
rake doc:app in a much smaller application:
Using that as a guide, I’m focusing these documentation efforts on my application’s classes, modules, constants, attributes, and methods. As you can see, I’m not very far into documenting this particular application.
I’m also a fan of Reek, and like to use it on my code prior to committing it and sharing it with my team. Its Irresponsible Module checker specifically focuses on the documentation issue, by making sure your classes and modules are documented.
We know what to document; now let’s talk about how to document. What should your documentation look like? I’ve got a few thoughts and suggestions.
In addition, the Rails API documentation guide is worth reading, for an understanding of what the Rails team looks for in documentation of the framework itself. While it’s not focused on documenting applications, it has several good suggestions on how to make your writing as clear and usable as possible. If you find yourself struggling to write in this style, check out the Hemingway Editor.
Finally, and most importantly, treat your documentation like it matters. I have written in the past about my code review practices, and now, I’ve added a step to check for documentation during the process. It only takes a couple more minutes during code review to verify that documentation exists and explains the new or modified code sufficiently.
I am actively applying documentation to some existing projects using this approach. It’s by no means final. I am curious to hear what you think about these ideas, and about how you handle documentation in your own Rails applications. Or, if you work with a different stack, how do you approach the challenge of documentation? What can the Rails community learn from yours?
Thanks for reading!
If you liked my series on practical advice for adding reliable tests to your Rails apps, check out the expanded ebook version. Lots of additional, exclusive content and a complete sample Rails application.
Ruby on Rails news and tips, and other ideas and surprises from Aaron at Everyday Rails. Delivered to your inbox on no particular set schedule.