Somehow it’s been a couple years since I wrote about “using VoodooPad for authoring help”:http://www.manton.org/2007/01/falling_in_love.html. I always meant to update the post with more information, and I still receive occasional follow-up emails from developers who are trying this for themselves. My workflow is virtually unchanged since then, and the help for “Clipstart”:http://www.riverfold.com/software/clipstart/ is built the same way.
Here is the Clipstart VoodooPad document in case it’s helpful to other developers: “Clipstart_Help.vpdoc.zip”:http://manton.org/misc/Clipstart_Help.vpdoc.zip. The important parts are the special pages WebExportPostflightScript and WebExportPageTemplate.
Meanwhile, “Philippe Casgrain wrote a great blog post”:http://developer.casgrain.com/?p=16 that is nearly identical to what I do, but with more detail and steps for triggering an export from Xcode. Lately I’ve been pointing people to his post since it’s more technical than mine was.
“Mark Dalrymple also posted”:http://borkwarellc.wordpress.com/2009/09/07/voodoopad-and-subversion/ a time-saving SVN script for VoodooPad today. I’ve been needing this!
VoodooPad is just a really good fit for this stuff. (Also see “Macworld’s 4-mice review”:http://www.macworld.com/article/141473/2009/07/voodoopad41.html for VoodooPad 4.1.) Or if you are more of an OmniOutliner kind of person, check out “Omni’s Helpify tool”:http://blog.omnigroup.com/2008/10/02/helpify-the-omni-help-emitter/ for converting outlines to an Apple help book.
A few years ago I used “VoodooPad Lite”:http://www.flyingmeat.com/voodoopad/ extensively. Every note, to-do list, and feature description went into it. At some point I migrated away from VoodooPad to a combination of text files and “Ta-da list”:http://www.tadalist.com/, perhaps fearing I would have too much data in a weird format that would be difficult to get at later.
But I was always on the lookout for a problem that would best be solved with VoodooPad again. With our localized help files for “Bookshelf 4.1”:http://www.vitalsource.com/, I tried for most of a day to use VoodooPad to manage the help. I even experimented with Gus’s dead “project for remote wiki editing”:http://www.flyingmeat.com/fs/flystashweb.cgi?space=3ec82d22-c72a-01d9-1639-c0cbe4c4c32b, thinking I would write my own web-based help-specific wiki system and plug “Boomerang”:http://www.flyingmeat.com/fs/flystashweb.cgi/348c223e-0512-01da-1c41-c0cbe4c4fc75 into it. In the end it was too difficult to force the existing static help files into VoodooPad.
Fast-forward to a few nights ago. “Wii Transfer”:http://www.riverfold.com/software/wiitransfer/ 1.5 has no Apple Help at all, and it needs some. A perfect opportunity for VoodooPad, and I’m happy to report that the solution works beautifully. I knew I could make it work because clearly VoodooPad’s own help files are managed with VoodooPad. After a bit of experimentation I bought a new VoodooPad license and all was well in the world.
Here’s how it works:
- I manage the help content in VoodooPad, creating pages for different help sections and generally just typing away and getting stuff done.
The HTML export template lives inside the VoodooPad document itself, so everything is in one place.
Also inside the VoodooPad document is a post-processing script (written in Ruby) that looks for a comment in index.html and inserts the appropriate AppleTitle and AppleIcon meta tags that Apple Help needs to get its work done.
The only part I haven’t finished yet is that the script should also send the files off to Help Indexer to update the search index. I coded that part but it doesn’t work yet — there is something different about how VoodooPad executes these scripts that prevents other applications from launching. (Maybe. I’ll sort it out eventually.)
You can “watch a screencast of the process here”:http://www.manton.org/screencasts/2007/voodoopad.mov. I add a new page, enter some filler text, export the VoodooPad document, then re-run the Xcode project and view the changes in Apple Help. Fun!