During my presentation at the API the Docs Chicago conference this week, I used an example from my time as a developer to describe a documentation cliff. I characterized it as driving along and encountering an obstacle, such as a muddy patch, that required extra effort to cross. Twenty-some years ago, I used to look for those situations to challenge my driving skills and my 1995 Land Rover Discovery, both of which were well suited to tackling them (however, the documentation of these events is still on paper and film, so I’m going to have to dig for some visual proof).
In the driving metaphor, to cross the challenge and continue on to the destination, I described employing the various tools on the vehicle, such as the four-wheel drive, “locking in the hubs” (a rather antiquated reference, these days), and pulling out the winch cable in addition to my driving skills. I was usually prepared (and often, over-prepared) for the challenges encountered in my off-road adventures, and if I wasn’t, the people I traveled with were. We usually arrived in tact.
I never realized the depth of this experience as a metaphor for my software development experience until I heard myself describe it in my presentation. While off-roading, not only was determining the destination a challenge (are we going to the right place?), but so was choosing the route, the tools, the pace, and the requisite skills to actually complete the trip. The parallels to my software development experience snapped into focus. The challenge of determining the right thing to do, the right way to do it, and the right tools to get the job done as a software developer became too clear to ignore.
In my presentation, I described this experience as what customers encounter when they use incomplete documentation. For example, when you see detailed on-boarding content (Hello World, tutorials, and such), it’s easy to get a sense that the company cares about your success with the API–after all, look at what they are doing to get you started. But, running into the documentation cliff, or mud bog to stick to the off-road driving metaphor, is what happens when a gap in the documentation abruptly halts your progress.Continue reading “Developing software and driving off road”