Take your mouse or trackpad or whatever, slide it over to that little wi-fi control in the corner of your screen, click and choose “Turn Wi-Fi Off” or whatever the equivalent is.

Now start a new project in your favourite programming language, framework, IDE or whatever. Can you do it?

This isn’t some macho “how much of an awesome hacker dude are you?” test. It’s not a test of you, it’s a test of your tools.

In most cases, the answer will be “not as easy as it should be”.

In an ideal world, I shouldn’t have to have Google at my beck and call in order to hack.

IDEs should make this easier. But the IDEs are not yet quite as simple as they could be. This evening, I’ve been working on a project to take two XML files, churn through them and basically merge the two (yeah, the XML community sold everyone a bill of goods on that; try RDF if you want a data model that trivially merges together). This shouldn’t be too difficult, right?

I have IntelliJ installed and I have Eclipse installed. I fire up Eclipse and realise that I don’t have the Scala module installed. I’m on a lousy 3G connection. I fire up IntelliJ, and everything has been buggered around with since I last used it for Scala development, and it doesn’t want to properly talk to Maven. Hate.

I could start a Java project, but I actually want to spend my time using the XML I’ve parsed rather than setting up an XML parser.

I eventually resort to just firing up MacVim and a Scala REPL and cmd-tabbing between the two. I’ll turn the results into a proper Maven project when I get home. But it’s still sort of a compromise.

I could have used Ruby and Nokogiri. The query I’m running on this XML is complex and slow enough as it is without wanting the penalty of Ruby’s shitty GC.

Ruby has lost a lot of the offline hackability that it once had. It used to be when you installed gems, RubyGems would generate RDocs. You could fire up gem serve and browse them in your browser offline.

And documentation is necessary in dynamic land. Consider something like this:

XML.load(file)

That seems pretty straightforward, right? Well, what does it take? A file name? A file handler object or reference? Something that satisfies some arbitrary and unspecified file-like interface (it has a readlines method, maybe)? A URL that it will proceed to load from the Internet? Damnit, documentation needed. If we were in a language like Java or Scala, we’d get documentation in the form of the type annotation:

XML.load(file: File)

XML.load(file: URL)

But without that type annotation, we need documentation. So where is it?

On the Internet, obviously. You know, the Internet you can’t access reliably when you aren’t either at home or in the office. The Internet we rely on for all our cloud services but which stops working when we’re inside train tunnels.

If I run gem serve, almost all of the gems have no documentation. I bet Bundler has been set by default not to store documentation because the process of downloading or compiling the RDoc is “too slow” or something. Well, what’s more slow than that? Not being able to do any programming because you can’t actually figure out the calling syntax of a method you are trying to use.

Python gets a lot closer. The help() function in Python’s REPL is pretty damn compelling. If you are hacking away in the REPL, you don’t have to shift context to use the help function.

Is it too much to ask that I can read documentation for the standard libraries of the programming languages I’m using on my own computer when I’m connected to the Internet? Is it too much to ask that offline documentation should be a default?