As mentioned on Twitter, Acorn 5's Help menu has a neat new feature- live searching of all our Acorn documentation:
I thought this was a neat trick, and I'll fill you in on the details of how it was done.
Step 1: You're going to need to write a whole new app which you're going to use to write all your documentation in. The one I wrote is called FMWrite. It's a really simple application which consists of an outline view which lets us organize the documentation, and it comes with a handy little RTFD editor. Throw in a little JavaScript, template support, HTML preview, and what it spits out is the documentation on our site.
FMWrite. Not an actual future product
That's not all it spits out though. When rendering the documentation (542MB of it, 1.22GB pre-render!), FMWrite also creates a SQLite index (1MB) of all the text content, which I then copy into Acorn's resources folder at build time. Acorn then ships with this SQLite file.
You don't really need to build your own documentation app. But you do need an index of your documentation to ship with your app. SQLite worked great for us.
Step 2: Let me introduce you to NSUserInterfaceItemSearching, which is a class which shipped in 10.6 but I didn't notice till about six months ago. It's a pretty simple protocol- you just register a class which conforms to it, and you're asked for entries when the user searches for something via the Help menu.
With Acorn 5, this means we perform a query against the SQLite fts4 table, and then return some entries which then show up as extra menu items. When a topic is picked, Acorn then just opens up a URL which points to the rendered version of the documentation on our server. And if your class also implements showAllHelpTopicsForSearchString:, Acorn will open up a URL on our server which hits a search index up there.
There is no step 3: If you make a Mac app, please steal this idea. Maybe even one-up Acorn and download updated help indexes from the server in the background. Or have the HTML files local and show that, with images rendered off the server? (Apple's Help viewer kind of stinks though, so you might make your own).
Small disclaimer: I'm sure I'm not the first person to do this. And if you're aware of any other apps that do- let me know! It's a neat feature and I'd like to see what else is being done with it.