• Read more about Keepin' Your API Honest

We've all come across API documentation that is out of date, lacking details, or just plain wrong! Often times an API’s documentation is entirely separate from the code itself, and there is no verification of the documentation's accuracy.

So how do we overcome this? Well, one solution for this problem is to generate the documentation as a result of passing acceptance tests.
The rspec_api_documentation gem allows you to write specs that generate HTML formatted documentation. The rake task included for running your doc specs is rake docs:generate, which puts the HTML files in the project's ./doc directory. If any specs fail, the documentation doesn't generate.
Once the documentation is generated, it’s time to add a documentation viewer to your API server.

There are two gems for serving API documentation:

• For rails use apitome
• For rack applications (like grape) use raddocs

Mounting the API documentation server as part of your API server and running rake docs:generate as part of the deployment process ensures your documentation is up to date and available.
So, if you're going to create an API, use grape, rspec_api_documentation, and raddocs to ensure testable, accurate, and up to date documentation. Your API users will thank you.

Included is an example repository using these tools here: api_documentation_template.

Feel free to comment, ask questions, or share! We'd love to hear from you.

• Read more about PROJECT README, Y U NO HAVE?

Pick any popular open source library. It'll have more documentation than your application code - I guarantee it. Test and documentation are both acknowledged as good development practices. But unlike testing, documentation doesn't get the same love from developers. For code that isn't intended for a public audience, developers keep all the docs in their head, or assume that their code is self documenting. Additionally, the tests become a kind of runnable documentation. But there's several lessons we can apply to our private application code from open source documentation. Today, we'll start the conversation with the lowest hanging fruits - the README.

The lack of a good README is one of my major pet peeves. When starting on a new project, more often than not, I'll find myself staring at this README:

== Welcome to Rails  Rails is a web-application framework that includes everything needed to create database-backed web applications according to the Model-View-Control pattern. 

That's a fantastic README introduction... for the Rails framework. But it also happens to be the default scaffold README for every new Rails project. Think of a README as a first impression of your project. Just like open source projects, your README should introduce the project the new developers.

Take 5 minutes of your time to write a README that explains the following things:

What is it?

A short elevator pitch about your application. Examples:

• Travis is an attempt to create an open-source, distributed build system for the Ruby community that allows open-source projects to register their repository and have their test-suites run on demand...
• YARD is a documentation generation tool for the Ruby programming language. It enables the user to generate consistent, usable documentation that can be exported to a number of formats very easily, and also supports extending for custom Ruby constructs such as custom class level definitions.
• Spree is a complete open source commerce solution for Ruby on Rails. It was originally developed by Sean Schofield and is now maintained by a dedicated core team. You can find out more about by visiting the Spree e-commerce project page.

How do I set it up?

List any dependencies your project has, both libraries it depends on, as well as external services it uses. Also remember to include any commands to start required services. Example:

Development Setup  # install redis, mysql brew install redis brew install mysql  # install rvm: http://beginrescueend.com/rvm/install/  # within the project directory bundle rake db:setup foreman start # visit: http://localhost:3000 

Project Workflow and Tips

Usually, I like to add an additional section for developers to add tips and tricks that help with their day to day workflow. The notes listed in this section are optional and individual developers can choose to use them or not.

Seed and Test Data

Often times, existing developers and stakeholders will have their environments configured and won't remember what seed data the system assumes to exist. Versioning a gzip dump of the test data is perfect for someone to come along and get a sense of what the app data looks like.

Who do I contact for help?

If the project is a client project, it's good to list the stakeholders and their roles. It's also a good place to put down the names and contact information for members who may have worked on the project in the past.

Relevant links

A list of links to other sources of documentation or project management tools.

• bug tracker
• comps, wireframes, and design prototypes
• wikis
• staging, qa environments
• other servers

Having a good README can help you onboard developers faster and have a single starting point for your project. It's easy and fast to write, so go forth and write yours today!

• Read more about Document Your Models the Easy Way

At a recent DCRUG meeting, I was surprised by how many Rubyists, novice and experienced, were unfamiliar with two great documentation tools: annotate_models and RailRoad.

I suspect this is because they relate to the dreaded “d” word: documentation. This is a shame, because these two tools make basic documentation a cinch.

annotate_models

One of the best things about the popular Ruby ORM libraries like ActiveRecord and DataMapper is that you don’t need to spell out the attributes of your models; they are inferred from the database.

Sometimes, though, it is useful to have this information at hand, instead of firing up script/console or your database to answer a simple question like: “Did he call it User.first, User.firstname or User.first_name?”

The annotate_models gem, originally written by Dave Thomas creates a nice comment block at the top of each model, displaying information about the underlying columns/attributes:

 # == Schema Information                                                          # Schema version: 20090311145521                                                 #                                                                                # Table name: groups                                                             #                                                                                #  id                     :integer(4)      not null, primary key                 #  name                   :string(255)                                           #  description            :text                                                  #  created_at             :datetime                                              #  updated_at             :datetime                                              #  status                 :integer(4)      default(1)   #

Producing this documentation is as simple as running annotate in your Rails application’s root directory.

Another nice aspect of annotate_models: it will only modify the headers of models that have changed since the last time it was run.

RailRoad

Another useful view of a Rails application, especially a legacy one, is the big picture: i.e., how do all the models (and controllers) fit together? This can be especially daunting when you are following the trail of :belongs_to and :has_and_belongs_to from one file to another.

A free tool, Javier Smaldone’s RailRoad, can tell you all that information at once, by generating a diagram of the models and key information about them, like names, attributes, associations and inheritance relationships.

A minor inconvenience is that the project’s models are outputted in .dot format. This is easily converted into .svg and .png if, like me, you prefer those formats.

Because I do this often, I have added the following alias to my ~/.bashrc and just run rr as needed.

 alias rr='railroad -M | dot -Tsvg > doc/models.svg; railroad -M | neato -Tpng > doc/models.png'

If you are happy with .dot files (e.g. you are a GraphViz user), it’s as simple as running railroad -M.

Another cool feature: you can use RailRoad to document your controllers too; just pass it the -C flag instead of -M.

Conclusion

Now, I know this hardly suffices as thorough documentation. However, I also know that I’ve been in web development for a decade and most projects I’ve seen have no documentation at all.

Complete documentation would be great, but it is time-consuming and requires good written communication skills — a tall order for your typical software engineer. Keeping that documentation up-to-date with rapidly-evolving software is even more challenging.

These two tools provide great “bang for the buck”. Check out the repository and run these two commands, and suddenly a legacy Rails application is far less opaque.

I run the commands manually, but you may also consider automating it as part of your build process, or even as a post-hook for rake db:migrate.

Either way, you can trust me on this: if you spend fifteen minutes installing these gems, a few seconds running annotate and rr, you will save hours over the course of your projects.