Jake Worth

• docs
• mac

One of my all-time favorite programming tools is Dash by Kapeli. In this post, I’ll share some tips for leveraging this fantastic program.

The ideal audience for this post is someone who uses Dash and wants to use it better. But in case you haven’t tried it yet, let me answer: what is Dash?

What’s Dash?

Dash is a MacOS application that offers offline access to, and a user interface for searching, hundreds of API documentation sets.

Why is that useful? I’ve learned that being able to find and share documentation effortlessly is a hallmark of a great engineer. Those who can quickly and correctly answer “how does this work?” can do incredible things.

But docs live on the internet, which isn’t an ideal place for reading them. Here are a few reasons:

• If you lose the internet, you lose the docs.
• It’s decentralized; each docset is stored at a different URL.
• Searchability varies by each docset’s implementation.
• Unofficial docsets for specification-based languages like JavaScript vary greatly in quality.
• The docs can change at any time: your favorite library upgrades, and now its website only shows the new APIs while hiding the older ones.

So we need quick documentation access, and the medium where they live is not ideal. Dash has solved this problem! I highly recommend it.

Here are my tips to use Dash better.

Focus the Search Bar with a Hotkey

Let’s start with something simple. command + L focuses the Dash search bar and is faster than pointing and clicking.

Keyword Searches

Dash offers keyword searches to limit results to a certain library. rails: transaction will search just my Ruby on Rails library, ignoring all other results.

This feature can be used to disambiguate different versions of the same library as well. Imagine I use Rails 7 for side projects and an older version at work. When I type in “ActiveRecord transaction”, which docset will be searched? Dash answers this question with keywords.

Since I need results from my work version of Rails to come up first most of the time, I can assign that library the coveted “rails” keyword. Rails 7, for my side project, then gets the keyword “rails_current”.¹

Now, I can search either library by keyword: rails: update_all opens the update_all docs page in the older version, while rails_current: update_all does the same in Rails 7.

Open the Online Documentation Page

Sharing your Dash docs with non-Dash users doesn’t have to be painful. Click the upload icon on any docs page and you’ll get the documentation’s official source URL in your paste buffer. It even includes a URL fragment (’#’) pointing to the function you need.

Searching the Internet

What if you don’t have the docsets downloaded, or you have them but the API you want isn’t included? Search more broadly by integrating search engines into the search bar.

Choose between Google, DuckDuckGo, or Stack Overflow. Below all the search results, or first in the list if there are no results, you’ll see the engines you’ve chosen.

A search for “elixir: noop” will search “elixir noop” in Google and DuckDuckGo, or “noop” on the Stack Overflow Elixir tag page.

Text Editor Integrations

Dash integrates with ~30 Mac programs! Here’s how I’ve integrated it with Vim.

With the dash.vim plugin, I can search Dash from Vim. Here’s how I’d execute the previous query from command mode:

:Dash update_all rails_current

This opens the update_all page of my Rails 7 docset in Dash.

Wrapping Up

A summary of these tips:

• Focus the search bar with command + L
• Keyword searches for limited and version-specific results
• Open the online documentation page
• Searching the internet
• Text editor integrations

Thanks to Dorian Karter for showing me Dash. What are your favorite Dash tips?

What are your thoughts on this? Let me know!