Search tools for API documentation

Continuing my quest for the perfect API documentation, this week I came across a site that offers a search over a set of API documents: Rails Searchable API Doc. Have you seen it before, or anything similar or even better?

I’ve written a couple of posts recently about API documentation, talking about documenting REST APIs and using tests as examples. People have added a lot of very useful and thought-provoking information via comments on both posts. Thank you everyone! This time, I’d like to show you a site that Jean-Michel pointed me at.

sdoc for searching Ruby APIs

The Rails Searchable API Doc site is developed by Vladimir. As the name implies, you can use the site to search the Ruby on Rails API documentation. The site is built by Vladimir’s tool sdoc, that adds a search feature into the documentation generated by RDoc. RDoc builds HTML documentation from Ruby source code.

Vladimir’s sdoc code repository is on Github. Here’s the readme.

Try it out!

Go to http://railsapi.com/. Here’s the gist of what you will see:

Tools for searching API documentation

Rails Searchable API Doc

Select one of the options above the big buttons, to choose the APIs that you want:

  • Rails
  • Rails and Ruby
  • Build your own

If you choose to build your own, you will get a list of APIs to choose from:

Tools for searching API documentation

Rails Searchable API Doc – select your APIs

Make your choice, click “Browse online” to see the API documentation, then enter a search term to see the dynamic search working. It’s in the left-hand panel:

Search tools for API documentation

Rails API search

What I like about this search is that it’s immediate. You see the results as you type. A very nice addition is  that you can select one or more sets of API documentation to merge into the search.

The search is smart. The first few results show matches that start with the search term you entered. Then come the results where your term is embedded somewhere in the string. Finally it shows results that may be a match: the characters in your search term appear in the result, but not necessarily sequentially. The front page has a quick guide to the features of the search tool.

Pretty neat, huh.

I want an sdoc!

I’m wondering how much sdoc relies on the RDoc format, and how easy it would be to adapt it for documentation generated by other tools such as Jersey’s WADL generator, Javadoc, Sandcastle for .NET, Doc-O-Matic, Enunciate, Doxygen. I’ve written to Vladimir, asking him for his thoughts on this.

Have you seen similar search tools on other API documentation sites?

BTW, a good API doc site

This is nothing to do with searching, but it is part of the quest for the perfect API documentation. Daniel is a fan of the Facebook developer portal. I’m impressed too.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 11 June 2011, in APIs, technical writing and tagged , , , . Bookmark the permalink. 4 Comments.

  1. You might be interested in this then:
    http://www.gotapi.com/html

    • Hallo plaindocs
      I love that! Thank you so much for the link. Cool: They offer a widget that you can grab to search a chosen documentation set. Looking at their blog, I see that there hasn’t been much action for a couple of years. I wonder what happened. Perhaps their development work is complete. The list of docs covered is impressive. Even ActionScript is there!
      Cheers
      Sarah

  2. RE: BTW, a good API doc site
    HI Sarah
    Is there a link to that good API site?
    Thanks
    Susan

    • Hallo Susan

      I guess the Facebook site is more of a developer’s portal than an API documentation site. Clicking through does get you to some very nice API documentation, like the page about the Facebook Credits API.

      Another great site is the Netflix API documentation. The first comment on the page says, “seems pretty simple”. That has to be a tribute to good documentation!

      Cheers
      Sarah

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: