I just finished a big task, significantly expanding some documentation. The original page was a summary of several ways to integrate with 3rd party systems, and an example of one of these methods. I used this document when I first tried to create an integration, and found it didn’t cover a lot of things I needed to know. So I wanted to improve it.
The document is now two pages, the example having been moved to its own page. I added more detail to the example itself, and a new section for additional topics it didn’t cover. The revised page is now online, and I’m excited to see it available for people to use.
Getting to that sometimes made me wonder how much I was actually making progress on my goal of a better docs page. There were other tasks to be done while this was happening, so it wasn’t all in one stretch. I had to learn to do the things I wanted to describe, which took lots of questions for more knowledgeable folks and experimentation to confirm my understanding. I made tons of notes, written with the hope they still made sense later when I needed them. Editing involved re-testing code examples to make sure I accurately described how they worked at an appropriate level of detail. By the end, in addition to the written material, I expanded one existing integration and wrote two entirely new ones.
The final result couldn’t have happened without preliminary exploratory work. The necessary information existed mostly in the personal experience of people who had done it before. Only some was documented. And, part way through, we decided my original idea of an entirely new document (with a new example) would be better incorporated into the existing material instead. So some partly completed writing was discarded, and extra work was needed to make the new code itself usable on its own. Wasn’t that inefficient? Does that matter? I see two different ways of looking at it.
One is that “All this is what brought me to this place.” The idea that the exploratory work was not only necessary, but important. Details that weren’t included in the final document shaped those that were, and tangents identified what was not central enough to the topic to merit space. The result wouldn’t be what it is without that work. To reference the joke in my title, this is like Carl Sagan’s apple pie, which could not exist without the entire history of cosmology that preceded it. (“If you wish to make an apple pie from scratch, you must first invent the universe,” from the original Cosmos TV show.)
The other way to think of it is that the preliminary work, or at least some portion of it, was an unfortunate necessity but not part of the actual work. Such yak shaving is often thought best to get through as quickly as possible. (“I want to install an app, but I have to upgrade my operating system first.”)
Sometimes it’s clear which camp something falls into. (I don’t need to write more OS upgrade documentation, for example.) Other times it depends on what the actual goal is. Is the information available, but in a less usable form? Then if the goal were doc updates as fast as possible, experimentation would be less relevant. (Or if less detail were expected.) But if the new working integrations are included, getting that code working would be very relevant. If personal learning is a goal, a wider range of things are fair game. Specific things may need to be time-limited, to keep on schedule.
My work for this doc task is on the pie end of this spectrum. The working code is relevant, not just a side-effect of research. The research was needed in any case because information wasn’t otherwise available. Learning is a specific expected outcome. That hasn’t always been the situation in a traditional job, something I have to remind myself here. My project updates now specifically include research and learning, they didn’t at first.
It sometimes felt odd to be dealing with a lot of “distractions,” or at least things that would normally be one in an average work environment. (“If it’s not in the plan, why are you working on it?”) But this is a different sort of thing, closer to a research project in some ways. Not knowing how tangential tasks would be viewed caused some stress. Yak shaving isn’t considered a good thing. But pies are ok. Particularly after I started thinking of them as first class tasks themselves.
Leave a Reply