Apple documentation search that works

2011-03-06 15:58:19 UTC

You’ve probably tried searching Apple’s developer documentation like this:

The filter field on the ADC documentation library navigation page.

Edit: That’s the filter field, which is not what this post is about. The filter sucks. This isn’t just an easy way to use the filter field; it’s an entirely different solution. Read on.

You’ve probably been searching it like this:

Google.

(And yes, I know about site:developer.apple.com. That often isn’t much better than without it. Again, read on.)

There is a better way.

Better than that: A best way.

Setup

First, you must use Google Chrome or OmniWeb.

Go to your list of custom searches. In Chrome, open the Preferences and click on Manage:

Screenshot with arrow pointing to the Manage button.

In OmniWeb, open the Preferences and click on Shortcuts:

Screenshot of OmniWeb's Shortcuts pane.

Then add one or both of these searches:

For the Mac

Chrome OmniWeb
Name ADC Mac OS X Library
Keyword adcmac adcmac@
URL http://developer.apple.com/library/mac/search/?q=%s http://developer.apple.com/library/mac/search/?q=%@

For iOS

Chrome OmniWeb
Name ADC iOS Library
Keyword adcios adcios@
URL http://developer.apple.com/library/ios/search/?q=%s http://developer.apple.com/library/ios/search/?q=%@

Result

Notice how the results page gives you both guides and references at once, even giving specific-chapter links when relevant. You even get relevant technotes and Q&As. No wild goose chases, no PDF mines, no third-party old backup copies, no having to scroll past six hits of mailing-list threads and Stack Overflow questions. You get the docs, the right docs, and nothing but the docs.

For this specific purpose, you now have something better than Google.

26 Responses to “Apple documentation search that works”

  1. Jeff Johnson Says:

    I’ve found that the order and quality of results are usually better from Googling site:developer.apple.com than from searching directly on developer.apple.com.

  2. Peter Hosey Says:

    Jeff Johnson: I’ve found the opposite. Google, whether I restrict to developer.apple.com or not, has gotten pretty consistently bad for me. Often, it’ll only turn up the PDF, not the specific chapter I want in the HTML doc; when it does show me what I want, it’s nowhere near the top. So far, Apple’s search (again, not the filter field) has worked very well.

    I only wish Xcode’s built-in search were this good.

  3. Peter Hosey Says:

    And, to be clear, that’s not Google’s fault. Apple’s had a bad habit lately of changing the links around for little to no apparent reason, with the result that Google-juice is not distributed as properly across Apple’s documentation as it once was.

  4. Erik Says:

    Forgive me if this is obvious, but you don’t even need to be using one of those browsers. Just create a two-line bookmarklet if you’re using a browser without custom searches. Save the following to a HTML document, then bookmark the links.

    Search Mac
    Search iOS

    [Links fixed by your humble host —PRH]
    [And now, bug fixed by your humble host; thanks to Andy Lee for pointing it out, and let the record reflect that it was my fault, not Erik’s —PRH]

  5. Erik Says:

    Sigh. Naturally I forgot to update the text in the anchor tag to “Search Mac”, and naturally WordPress ate my HTML. But you don’t even have to go to the trouble of creating the HTML document anymore. Just drag those two links and rename the first one.

  6. Erik Says:

    I should just stop talking. Please disregard my previous comment, I spoke without actually testing the links. But I’m sure everyone gets the gist.

  7. Andy Lee Says:

    There’s a Safari extension called “ADC Search” that provides a dedicated text field that I assume does something similar.

    http://acmeinc.org/extensions

    Takes up some screen space, but one could add a keyboard shortcut for the menu item that toggles the view on and off. Or figure out from the source code how to do what Erik mentioned. Also you have to click on the field — it’s a pain to tab into.

  8. Andy Lee Says:

    Weird, I’ve no idea why my “‘” characters got backslashed.

  9. Jane Says:

    Or set up a custom search for Alfred – http://developer.apple.com/library/ios/search/?q={query}

  10. Peter Hosey Says:

    I’ll go through and fix up the markup on your comments.

    I would assume any browser extensions use the filter field (which is powered by JSON), not the search. The filter sucks.

  11. Peter Hosey Says:

    Erik: Your links should be effective bookmarklets now. I hope I didn’t take too much creative license in filling them out. At any rate, bookmarklets are a good idea—good thinking.

  12. Andy Lee Says:

    Well, the Safari extension returns the same four-column search results, and also includes links to key doc pages at developer.apple.com. BUT the bookmarklet only uses a bit of my bookmarks bar, and by putting it near the beginning of my bookmarks bar (in Safari) I can get to it with Command-1 or -2 or whatever, with keyboard focus right where I want it. So — many thanks to Peter and Erik!

  13. Andy Lee Says:

    Okay, a nitpick with the bookmarklet: if I hit Escape it doesn’t cancel the search, but rather does a search for “null”. I’ll take a look later and see if I can offer a fix.

    Thanks again. I blogged about this here: http://www.notesfromandy.com/2011/03/07/great-bookmarklet-for-searching-the-docs/.

  14. Matt Butch Says:

    Awesome, thanks for the tip. This makes it so much easier to search the docs. And also, its a great reason while I still use OmniWeb.

  15. Peter Hosey Says:

    That’s no nitpick, Andy; that’s a valid bug report. I fixed it in the links in Erik’s comment above.

    Anybody who’s previously saved those bookmarklets should re-save them.

  16. Andy Lee Says:

    Thanks, Peter. I’ve updated my blog accordingly.

  17. Piet Jaspers Says:

    I’ve been using a variation of this by using Alfredapp and a shortcut, works very nice.

  18. Gerry Panganiban Says:

    Also works great w/ the PopSearch Safari Extension: http://canisbos.posterous.com/pages/popsearch

  19. Tommy Bollman Says:

    Thank you very much, this was indeed helpful.

    There is a port called AppKiDo over at http://www.macports.org, that I’m eager to try, but I haven’t come that far. Well, I’m comitted to try it every way since I already have decided so. But this is way beyound better than using google. -I have been so tired of writing “site:developer.apple.com” Thanks

  20. Peter Hosey Says:

    Tommy Bollman: AppKiDo is a native Mac OS X application, so you can get it directly from the developer.

  21. Mark Anderson Says:

    I don’t use Chrome or OmniWeb. I use Safari and I also use LaunchBar. LaunchBar let’s you create “Search Templates”. Here are the two I created using the above info:

    iOS: http://developer.apple.com/library/ios/search/?q=*
    Mac: http://developer.apple.com/library/mac/search/?q=*

    These let me invoke LaunchBar, type my shortcut and search on the fly in Safari.

  22. Chris Lawson Says:

    This also works in Camino, with the same links you give for Chrome. (I believe Firefox also supports the same thing, but I couldn’t swear to it.)

    cl

  23. Jamie Kirkpatrick Says:

    Hi Peter

    Had this open in a tab for a few days and just got round to setting it up: epic failure ensued! http://bit.ly/ezpCfd . Not a problem with your tip per-se but wtf? Google returned the correct result first time :(

  24. Peter Hosey Says:

    Jamie: Kooky. It still works for me. Did you retry it?

  25. Matt Neuburg Says:

    Good idea. Easily adapted for LaunchBar.

  26. Josh Caswell Says:

    What a great tip! Thanks, Peter.

Leave a Reply

Do not delete the second sentence.