YARD sale clearance

We’ve previously stated our commitment to rdoc.info as the official documentation home of our open source projects.

Add the documentation for Clearance to that list.

Why

Blog posts and wikis are good for tutorials, not for API documentation.

YARD is awesome. Take five minutes to scan the Getting Started page.

rdoc.info is open source. I’m happy to outsource documentation generation and serving like any other service such as source code hosting or error notification tracking.

Positive side effect: visibility

The process of documenting with YARD made me think harder about public/private visibility. I was surprised that documentation could be a design tool.

Looking at the public API, I noticed how many methods are required to handle the remember me as a “feature”.

If we go to a Github/Tumblr model, the API will be simpler and the implementation would be cleaner.

Apology

We began working on Clearance during last year’s Lone Star Ruby Conference. Announcing the official API documentation home should not have taken a year.

I used to think “the code is documentation” but I no longer believe that is true.

Using YARD and rdoc.info to document code proved to be easy (under an hour of work) and the meta process improved the API, encouraging a limited scope through opinionated constraints.