Thinking away from the computer

Over the past week I started to work on the implementation of the programming language for my honor thesis. On Monday I created a fresh Git repository and started writing some code. Though I sat in front of a machine for close to three hours, my total contribution amounted to about 50 lines of C, almost all of which was just struct definitions. I did solve some problems but there were a lot more implementations questions that I left answered (including most of the important ones). Suffice it to say that at the end of Monday night I felt like I really hadn’t accomplished that much.

I suppose that one problem could have been the annoying sophomores sitting at the other end of the lab complaining about their CS102 homework and checking Facebook and setting their party schedules instead of actually doing any work. However, the more important reason is probably that I sat down with the expectation of just being able to write code and do my thinking on the fly. That’s worked in the past, but thinking back on it, that only strategy only really works when I have a solid problem description and a good idea of what it is I’m trying to build. When I’m working on my thesis though, the question is a lot more vague and I have a much less definite idea of what I’m trying to build. Sure, I know the features I want my language to have, but it’s a different question entirely of how I’m getting there.

Yesterday I took a different route. At around 8pm I found myself in the odd position of having a half-hour until I met a friend to talk about homework. Now I generally consider half an hour to be too short a time to do anything really productive (unless it’s something simple like looking up papers or websites). But for some reason I decided to sit down in and think about some of the problems that had stumped me the night before. I found a nice comfy couch in the library and pulled out a simple lab notebook that I carry around with me all the time. I spent about 5 minutes just rehashing what I’d already written out in C code and making some changes. But in the 15 minutes after that I came up with (what I consider) a rather decent solution to one of the more important problems that had stumped me the night before.

I was really surprised that I could do in 15 minutes what had taken up more than 3 hours the night before. I’m aware of a lot of evidence that suggests that the best ideas come after your brain has been soaked in relevant information and thought patterns for a while. In that light, it’s perhaps not surprising that I had a eureka moment after a night of concentrated thought. However, I think that a significant part of the problem is being able to step away from the computer. Despite the fact that I love writing (both code and text) as a form of “thinking out loud” and that I don’t usually go into rapid task-switching when I’m “in the zone” on something, I think that sometimes just the very act of staring a screenful of code can make you blind to solutions.

The blank text editor buffer is a scary place. You’re sitting there trying to write the awesome piece of software that’s going to change the world and make you a billionaire in the process, and you have absolutely no idea how to start. While I’m all for starting out small, building a prototype and taking it from there, sometimes even getting started can be a pain. The second problem is the very nature of programming itself: it’s all about rules and structures. You’re writing in a language with syntactic and semantic constraints, you’re building a system of complex rules and systems and it can be very easy to get bogged down in it or get overwhelmed by inertia and keeping going down a wrong path (without even realizing that it’s the wrong path). While having rules and constraints can and do make a design better and leaner, at some points you need to relax the rules so that you can get a higher level view of things. After that you can come back down to earth and start making things fit the rules of the system.

For me my problem was that I was trying to write functional code while all the design ideas I had were very high level. I needed to establish some sort of middle ground so that I could make low-level design decisions without having to fit it into syntactically correct code at the same time. Unfortunately, while I was sitting in front of my machine with my Emacs buffer open, all I could think about was C structs and functions. Being able to sit down with a pencil and paper and no computer in sight allowed me to take a step up and do design work without being tempted to produce correct C code. At the end of my 15-minute eureka session last night, I had about 10 lines of pseudo-code and 3 diagrams that specifying a concrete implementation of what I needed to build. Since it’s not actual C code, it’s going to need some work to get implemented, but it’s a great start.

Right now I have about 6 hours a week (two 3-hour blocks) that I plan on devoting to implementation work. I’m going to be setting aside another hour or two in the week to do computer-less work. I’m a great believer in creating your own luck so I’m interested in seeing just how lucky I can get.

Aiming for the Cloudtop

In my day-to-day work I end up using a number of physical machines and all three major operating systems. I do most of my work on Linux, but I use Windows machines for all my electrical engineering work (mostly MATLAB and a few design programs). I use my Mac Mini for my music and videos and if I need to use a computer at the library I prefer using their iMacs. I often find myself needing to transfer files between machines (especially if I need to print something). Even the school gives students a gigabyte of space on a network drive, I never got it to work on Linux. In the past I’d use a combination of email and USB drives to moce stuff around, but a few weeks ago I started using Dropbox and I’m quite happy with it.

I haven’t been able to quite pin down what makes Dropbox successful when other similar applications haven’t done so well. I think a large part of the reason is that Dropbox seamlessly melds the cloud and the desktop. They have desktop apps for Windows, OS X and Linux that all actually work. The way I use it Dropbox acts as simple folders on my local machines and are immediately synced with the corresponding folders on all the other machines. And whenever I’m at a computer where I can’t install Dropbox, I can just use their web interface (which is well done and very frictionless). It also helps that Dropbox gives me 2GB completely for free. I have friends who are pushing that limit already, but since I just put stuff like homework I need to print off, that should last me a while.

Part of the reason for why Dropbox feels so easy to use (and I becoming very popular) is that it seamlessly fits in to the way you work. Dropbox doesn’t sell itself as a backup or some kind of complex, high powered auto-syncing solution. It does one thing well — keeps a folder exactly the same on all your machines. You don’t have to manually upload files to a webservice or specify which folders you want to sync and what not to. You just put everything in one place (your Dropbox) and rest assured that it will be the same on whatever computer you’re on.

As Anil Dash says, the key to apps like Dropbox and Evernote (which I don’t use myself) is that they inhabit a sort of “in-between” space that exists across both the web and the desktop. They don’t try to deny to deny the presence of the desktop by offering an all-powerful web UI. Instead they embrace the idea that you’ll be using multiple heterogeneous platforms. The web is just yet another interface. They also offer an API meaning that developers can’t extend it for purposes that the original service provider doesn’t support. Another aspect of these apps that I find refreshing (as compared to Delicious for example) while they allow for sharing and a certain social environment, it isn’t central to the service’s operation.

I’m hoping that these sort of “cloudtop” services get more traction as time progresses. In particular, I’d love to see things like user preferences be synced as well as folders and data. On a parallel note, I’d like to export services already present in applications get streamlined as well. As an example, iPhoto allows for export plugins so that you can directly upload your photos to places like Flickr, Picasa or Facebook. Unfortunately the upload process generally blocks the whole app instead of happening seamlessly in the background. I think we’re getting closer to a future where all our data is available seamlessly everywhere. I hope there isn’t too much fragmentation in the area as it would a pain to have to use half-a-dozen different apps to keep my data in sync (especially if they’re all using a different way to do it). This market is still in its infancy but apps like Dropbox are leading the charge and they promise to make computing much easier all involved.

Thinking about Documentation

My friend Tycho Garen recently wrote a post  about appreciating technical documentation. As he rightly points out technical documentation is very important and also very hard to get right. For someone who writes code I find myself in the uncomfortable position of having my documentation spread out in at least 2 places.

A large part of my documentation is right in my code in form of comments and docstrings. I call this programmer-facing documentation. It is documentation that will probably only be seen by other programmers (including myself). However, even though it might only be seen by programmers who are using (or changing) the code doesn’t mean that it should just be in the code. More often than not, it’s advisable to be able to have this documentation exported to some easier-to-read format (generally hyperlinked HTML or PDF). Of course I don’t want everyone who wants to use my software to go digging through the source code to figure out how things work. A user manual is generally a good idea for your software no matter how simple or complex it might be. At the very least there should be a webpage describing how to get up and running.

One of the major issues of documentation is that it’s either non-existent or hopelessly out of date. A large part of the solution is simply effort and discipline. Writing good comments and later writing a howto are habits that you can cultivate over time. That being said, I’d like to think that we can use technology to our benefit to make our job easier (and make writing and updating documentation easier).

Personally I would love to see programming languages grow better support for in-source comments. Documentation tools like Javadoc and Epydoc certainly help in generating documentation and give you a consistent, easy-to-understand format, but the language itself has no idea about what the comments say. They are essentially completely separate from the code even though they exist side by side in the same file. I would love it if languages could work together with the documentation, say by autogenerating parts of it, or doing analyses to detect inconsistencies.

As for documentation that lives outside of the code, I’m glad to see that there is a good deal of really good work being done in this area. Github recently updated their wiki system so that each wiki is essentially a git repo of human-readable text files that are automatically rendered to HTML. Github’s support for Git commit notes and their excellent (and recently revised) pull requests systems provide really good systems for maintaining a conversation around your code. The folks over at Github understand that code doesn’t exist by itself and often requires a support structure of both documentation and discussion surrounding it to produce a good product.

So what’s my personal take on the issues? As I’ve said before I’m starting work on my own programming language and I intend to make documentation an equal partner to the code. I plan on making use of Github Pages to host the documentation in readable from right next to my source code. At the same time, I’m going to giving some thought into making documentation a first class construct in the language. That means that the documentation you write is actually part of the code instead of being an inert block of text that needs to be processed externally. The Scribble documentation system built on top of Scheme has some really interesting ideas that I would love to look into and perhaps adapt. Documentation has always been recognized as an important companion to coding. I’m hoping that we’re getting to the stage where we actually pay attention to that nugget of common wisdom.

Is HTML finally getting there?

I just finished my first presentation done completely in HTML5. Ever since I made the move to plain text for most of my writing a few years ago I’ve been looking for a way to make presentations without resorting to PowerPoint or Keynote. I knew that I could use PDFs but somehow just throwing up static PDFs onto a screen didn’t really seem the best for a presentation.

Recently a very well done HTML5 presentation demo made the rounds on the intertubes. On the HTML5 Rocks website they had a template for the presentation and so I downloaded and used it to roll my own. It’s not the flashiest thing in web, but it certainly holds its own against most PowerPoint presentations and is definitely better than any PDF presentation I’ve seen.

Making that presentation brought me around to the view that maybe, just maybe, HTML is getting close to becoming a usable and fairly universal documentation format. The combination of HTML5, CSS3 and faster JavaScript engines becoming commonplace has made things like HTML slideshows not only possible, but actually attractive. I think we’re at the point where we can seriously consider completely ditching proprietary binary formats (I’m looking at you, Word) and go for full-on hyperlinked documents as our main format for sharing information.

That being said, I’m not saying that writing in HTML is the best thing to do. After HTML is a flavor of XML and writing bare XML by hand is just painful. The only case where writing HTML by hand makes sense is when you want really good control of the layout (like on my static webpage). Creating the presentation in pure HTML was a good learning experience, but I definitely want to wrap it in some sort of templating system. What I really want to see is powerful tools that write to HTML and CSS for the styling and content and maybe even auto-generate custom JavaScript for animation and the like.

One of the best systems that generate HTML is the Emacs org-mode. The documentation for my last project was written entirely in lightly marked up plain text and automatically converted to HTML. The only code I really had to write was the CSS for it, which is pretty simple. It might be possible to use org-mode for generating my slides too, but it’s not something that I’ve explored in any detail. It’s certainly possible to create PDF slides (using export to LaTeX) and perhaps some variation of that will work for me.

Even though Google Docs is pretty decent tool, I feel they’re woefully under-utilizing HTML5’s true potential. In particular the slideshow app is very bare bones when it could easily be much better. Strangely enough, Google has made some really strong inroads in other areas. For example, their font API lets you use a number of really good fonts by just including a few links of code in the header of your HTML. Google Docs should really be able to plug into their font API and let us use those fonts in docs and presentations.

I really think that we can live in a world where HTML provides all our text documentation needs (and efficiently includes audio and video as needed). I’m going to be starting a little experiment where all my documentation for my honors is done in plain text and automatically exported to clean HTML. I’m also hoping that for my final written thesis I’ll be able to write in some plain-text source format (probably org-mode) and do painless exports to both good-looking HTML and LaTeX for making print PDFs. I’ll also be using HTML5 for all my presentations from now. Stay tuned over the next few months on how these experiments turn out.

Sunday Selection 2010-09-05

Reading

How do I write so much? I’m glad you asked is something I think all bloggers and academics should read. I think writing is  a very good way to practice thinking and spread your ideas and this article describes both why and how you should increase your writing throughput.

Media

Google Priority Inbox video While priority inbox by itself is a very useful feature for people dealing with lots of email, the video itself is a work of art. It’s really well made and I found it both entertaining and informative

Software

Google Priority Inbox is probably best thought of as a spam filter in reverse. Instead of removing spam from your inbox, it places important email in a “priority inbox” that shows up as a section on top of your main inbox. If you get lots of email a day this is for you. I suggest changing the settings so that important emails are shown in the priority inbox even after they’re read. That way it’s easier for you to find important mail after you’ve read it.