Integrating offline documentation into my workflow with Dash

People like to compare programming languages, or their favourite framework. Everyone tends to have a favourite and the subsequent discussions (arguments/flame wars) very rarely add any value. Lots of non-PHP programmers delight in the various “php sucks!” articles, sometimes they’re right but often they miss the point. PHP can suck but so can any programming language when used incorrectly. That said, i’m pretty fond of PHP. Its been my programming language of choice for the last 10 years give or take. I happen to like it and I tend to think there’s a lot to like about it. If I was to distill this down to a killer feature though (as people tend to do) then i’d suggest its nothing in the language itself. For me the killer feature in PHP has always been the documentation. The PHP docs rock, they look awful (hopefully not for much longer) but they add so much value to the language its untrue. The comments too are usually excellent. I’ve lost count of the amount of times where the answer I was looking for (whatever the question) was either answered by the documentation itself or the user contributed notes beneath. If you’re a PHP dev then you will have found this too – 100%. The only problem with the PHP docs is how much I can rely on them at times, and that they rely on an active internet connection. Now, admittedly this is few and far between but there are times when internet is flaky or non-existent – travelling on trains, planes (or automobiles) for example. Recently though I’ve found a solution to this issue – a great Mac App called Dash

Screen Shot 2013-02-23 at 21.12.45
launching dash from Alfred

Dash. Dash describes itself as “… an API Documentation Browser and Code Snippet Manager. Dash stores snippets of code and searches offline documentation”. You want a searchable copy of the PHP docs available offline then Dash is for you. Of course, Dash is not limited to PHP. There are docsets for most languages and libraries you can think of. This is already powerful. Recently though i’ve picked up on a couple more features in Dash that make it really killer for me and now, whether I have internet or not, I tend to use Dash for all documentation reading. One of these things is the hookup it has with Alfred, another excellent Mac app. I can launch Alfred with the shortcut ⌥+SPACE, and by typing “dash SOMETHING” the docs are immediately searched for that item – for example “dash array_intersect“.

Screen Shot 2013-02-23 at 21.27.48
A function definition file within Netbeans

This is pretty sweet. Its quick, its offline, and somehow it feels distraction free as its outside of the browser. This definitely scratched an itch for me, I wondered if Dash could do anything more that I would fine useful. It turns out it could. I’m a big fan of the Netbeans IDE for all my PHP development. Yeah, I know all the cool-kids are using Sublime Text with its infinite customisation but I like Netbeans. I’ve been using it for years, i’m happy with it. One thing i’ve never liked so much though is the way it handles documenting core php functions and libraries. Hovering over a function will display the Phpdoc for that code, where as ⌘+Click will take you to the function. This works great for custom code but not so great for the core  language code.  I want to see this documentation on the PHP site, the Netbeans method of displaying it within a function definition file just doesn’t cut it. Fortunately i’ve found a method of integrating Dash here too – using the “Look up in Dash” System Service. I’ve been a Mac user for about 3 years though and i’ve always been a little confused by services, this is the first time i’ve made any use of them. Through a System Service within Netbeans i’ve been able to connect a shortcut in Netbeans to the Dash service. I’ve chosen ⌘+⇧+D. By highlighting a piece of code, and using that shortcut Dash is launched and searches immediately for that code. Of course you can use any shortcut you like but this works for me. Pretty simple in the end, and now I have Dash linked into my workflow quite effectively.

Leave a Reply

Your email address will not be published. Required fields are marked *