Developing software and driving off road

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.

In API documentation, that gap looks very similar to the driving experience. One minute you’re happily coding away, applying the new API, and adding new features to your product. The next minute, you’re stuck trying to debug and reverse engineer a library or REST interface to figure out how it works or what a parameter should be because it wasn’t documented sufficiently.

In Chicago, I knew I was in the right crowd by all the heads that nodded in recognition of that experience.


It wasn’t until after the conference, most likely on the plane back home, that I associated selling my Land Rover with leaving software development. I don’t know if one caused the other or if both were reactions to other things in my life (I’m guessing the latter), but I felt about software development in much the same way I felt about off-road driving.

I’d been developing software professionally for about 15 years and the problems seemed to be repeating themselves and only the language was changing. First in FORTRAN, then in C, then C++, then COM, then… well that’s where I bailed. I’d been there, done that, and had more t-shirts than I knew what to do with.

Off-roading, I’d also been there, done that, and collected a few t-shirts. I’d seen most of the trails within a few hours from my house. Most of them just went up somewhere and ended. After a while, I could make it through the trails–often past the point others turned around. It took some practice (and some vehicle repairs) to learn to do that. However, I was at the point where I could tell, in advance, if the trail would result in vehicle damage or not; and I could go most places that wouldn’t damage the Land Rover (too seriously).

But, the novelty of the new challenges had gone and traveling to new places to explore took more time than I could spare. So, I traded the Rover for pickup.

A couple of other things also seemed to happen at the same time. My software development skills needed some maintenance. Honestly, I’d not kept up with the field. I think my view of seeing the same problems over and over was self-inflicted and, ultimately, career limiting. Rather than tackle new challenges where I’d be learning (and less productive) I stuck with what I knew and was getting bored with it.

At the same time, my Land Rover seemed to need more and more maintenance, which meant less and less driving. After a point, I just assumed that anything I fixed would be temporary–especially the oil leaks.

What does this have to do with API docs?

Well, after all this I became a technical writer or, more precisely, a programmer-writer. But, that’s not the point of this reflections.

In my talk I mentioned how encountering a gap or omission in the documentation was like encountering a mud bog or other impassible obstacle. For me, as a documentation consumer, that’s how it feels. Cruising along one minute; ground to a halt the next.

A common (albeit unproductive) attitude I encountered as a developer went something like, “Well, a smart engineer can figure it out.” Yes, of course they can, but the implication was a shortcoming in documentation was simply highlighting a shortcoming in my skill set. I know now, that’s not how it works.

In my Land Rover, I could always spool out the winch and pull myself (and others) through the obstacle. But, that’s MUCH slower than cruising to my destination. Of course, in my Land Rover, we were rarely under schedule pressure and we actually went looking for obstacles (imagine a hackathon for Jeeps and Land Rovers).

As a developer, however, I wasn’t being paid to sort out someone else’s code (well, that’s not entirely true; sometimes, that actually was my job, but that’s not relevant to the story). While I was certainly capable of debugging and reverse engineering (a skill honed through lots of practice), that was never scheduled; although, I believe we tried a few times.

Is this going anywhere
(or will we need the winch)?

In my presentation, I had a sudden empathy for the customer and how documentation can pave the road to their success or present obstacles to their success. The documentation isn’t acting alone the API’s design and usability also contributes to the nature of the customer’s road to success with an API; but this was a documentation presentation.

The nature of this path is important to me, because I see my role as a writer to make that path as smooth as I can for readers. That can be daunting at times, and writers have their own set of obstacles that make that job a challenge.

If there’s anything to take away from this, it’s understanding the nature of your road to success. Is it paved (rarely), bumpy, mountainous, muddy? Further, knowing the nature of the path and the obstacles that lie ahead can make it easier to navigate the obstacles–avoiding some, paving others, and sometimes just powering through them. This applies to the road to successful technical writing as it does to paving the road to a successful customer experience for the readers of the documentation we write.

Leave a Reply