The Ruby API documentation site is an open source project, initially started by Colby Swandale, and supported by Ruby Together.
Ruby API received an exciting update recently: the core Ruby type signatures are being imported into the app. Eventually the type signatures will be able to be parsed directly in Ruby API.
“It’s all about being able to offer a richer developer experience to people by seeing the exact details of each method,” says creator of the app Colby Swandale.
The current Ruby documentation is written in code comments, and as a result is not always consistent with the code itself.
This latest update eliminates that. Instead of method examples being written by humans, they will be written by a computer.
preview of Ruby 3 type signatures
Colby is excited about the ability of Ruby API to provide much more context about the return values of methods. For the user this means a better understanding of, for example, which arguments are optional and which are required, and which keys are needed in hash arguments.
“By being able to infer the type signatures you can infer directly from the code. So you can ensure that the accuracy is a lot better.”
With such a vast improvement to the documentation searchability on the horizon, it’s hard to believe that just a two years ago Ruby API almost ceased to exist.
The Ruby API Story
Colby was inspired to create the Ruby API app in 2018. He says it “was a passion project of mine but it was born out of frustration.”
At the time there was no one reliable place Ruby developers could easily search for items in the documentation they were looking for. A combination of the large number of sites using generated docs and Google’s difficulty understanding Ruby documentation, led to confusing and inconsistent search results. Often a search of the documentation would return several outdated or irrelevant versions of Ruby.
On the sites that were available (https://www.ruby-lang.org, Rubydoc.org and API doc) the UI on mobile and tablets left a lot to be desired. Over two years, and four iterations Colby set out to create a solution — having varying success with either the search feature or the UI but struggling to have both operate well at once.
Then, he had a eureka moment in a conversation with a friend who happened to be taking a course on Elastic Search. He did some research into the search engine to find out more. It turned out Elastic Search had the exact features he was looking for to improve the search, and provide the results he was looking for.
“You could do things like give priorities to arbitrary values, so if you search for a method that’s in, like, a string, the core Ruby class would get the highest search results.”
With a search feature that finally seemed ready, and a new found rush of motivation Colby got momentum to design a UI that was fully responsive on desktop, mobile and tablets. In early 2019 he shipped the first version of the app on Heroku. As a soft launch, he shared the link out with a few members of the Ruby community to test and received positive feedback. Then he posted the link publicly on twitter.
The result was basically, crickets. There wasn’t much site traffic. “I think it was like, maybe less than five people a day were using it,” he says.
Admittedly, Colby says he didn’t make a huge promotional push. He didn’t post about the app on Reddit, Hacker News or any other large platform where developer content often goes viral. Instead it was spread by word of mouth.
After a few months of low usage, Colby’s motivation to maintain the project was dwindling. He decided to shut the Ruby API site down, leaving the project open only on GitHub for users to run on their own. He made an announcement about it on twitter. It was then he realized just how useful the site was to Ruby users.
An outpouring of support came in from people who had been using the app. Users reached out to ask him not to take it down.
Friends in the Ruby community shared their enthusiasm for Ruby API on twitter, Hacker News, and the Ruby subreddit. It was even added to the list of resources on the official Ruby documentation website.
“People were very vocal, and that was a huge motivation,” says Colby.
Ruby API received a huge surge of traffic that day. Importantly it confirmed Colby’s initial hunch that the Ruby community needed a new and improved approach to documentation.
“They gave me validation that I was actually on the right path — that there actually is a problem, people know there is a problem and we’re all seeking for something better.”
The Future of Ruby API (And How You Can Help!)
Aside from type signatures, there are a few other features Colby would like to add to the app down the line.
“I eventually want to bring all gem documentation into Ruby API,” he says.
The most important part of the Ruby API story to him is how crucial it is to hear from users.
From the chance conversation with a developer friend that spurred the app, to the community of beta testers, to the Ruby users whose feedback have resulted in some of the features the app has now (like being able to run code examples) — the app is what it is because of community support.
“This is a project that anyone can help make better. This is a project for the Ruby community and I would love to have their input to help make Ruby API better.”