A software engineer's most important skill is optimizing for learning1.
Everything we do in our work relies on having learned something, and often it relies on having learned it for the first time just a few minutes ago. So, the truly skilled software engineer is able to learn something and then turn around and put that new information into practice within a few minutes.
This learning loop typically looks like this: Write some code to try something → It doesn’t work → look up why it didn’t work → read, learn → try again with the new information in mind.
In this loop, the most effective way to gain the needed information is to read. We’ve all been frustrated when the information lives in someone’s head rather than on a web page somewhere, forcing us to talk to that person to get the information out. Talking is slow, and now you have to use two people’s time.
I’m continually surprised, then, how casually reading skills are ignored in our industry. Obviously, I’m not talking about simply reading; I’m talking about reading well.
As much as I’d love to, I can’t blame the software engineering industry for the lack of education on this topic - it's actually a nationwide problem. The US Department of Education estimates that half of US adults lack literary proficiency. A quick search online reveals that college graduates also suffer from low reading skills.
Reading is the most important general-purpose skill a person can have. Writing is right behind it. We think we’re done improving our reading once we graduate from 6th grade, but that’s simply not true. The skill cap for reading is so high it might as well not exist. It’s something to practice throughout your life.
When I realized this about reading, I knew I had to get better at it. And so I read how to read a book. I want to summarize a few points that I now apply in my reading of technical documentation.
Purposeful Skimming
The first thing to do on a new documentation site is to skim. This is assuming you haven’t been there before and the technology is new. Most recently, I did this with Tekton.
Skim the introduction, installation, and “getting started” guides, and try to understand what the technology is for. If there’s a word you don’t understand, skip it for now. This is quite a common occurrence if the whole domain of this technology is new. We’ll come back to those words later.
Most documentation sites have a sidebar that acts as a table of contents. Turn your focus there and read through every header and sub-header, mentally noting the ones that sound like what you want to know more about. If you notice that the site is huge, don’t despair. Skip any parts that don’t seem important.
If there’s a “concepts” header, definitely note that down. Any documentation dense enough to need a “concepts” section is likely to use lots of lingo that you’re unfamiliar with. Open up any links to videos. You’ll want to watch those in the next section.
Once you’ve read through the contents sidebar, open those pages that sounded most applicable to you and skim them separately. Notice that I’m not suggesting you read every word on the whole site. Right now, the focus is to find the parts that will be most valuable as quickly as possible.
Detailed Reading
Once you’ve skimmed the introductory parts and the others that sound important, it’s time to read in some more detail, top to bottom, those parts that were important or interesting.
I usually start back at the introduction with this. In the case of Tekton, there are some videos there that I’ll watch instead.
In this part of the reading journey, you don’t need perfect understanding. That will come when you start practicing with the technology. You just want to understand what the technology does, how it works, and why you should use it. By the time you finish this reading, you should be able to explain what it’s used for and how to install and use it.
When you come across those words we skipped in the previous section, now is the time to look them up. They might be new technologies you’ve never heard before. In this case (if you have the time), you can do a quick skim of that documentation. Otherwise, skim online until you generally understand what those new words mean. With Tekton, I had to learn a few basics about Kubernetes and the tools surrounding it, like minikube and kubectl.
Practicing
The two steps before this vary in time needed, but I would guess it might take 30 minutes for a medium-large site. This is where the fun begins. It’s time to practice.
This is where you do the steps in a fresh project in the “installation” and “getting started” guides. You’ll have to read in far more detail here, and we don’t have all day, so it’s important to make quick value judgements during the previous step about what sections are the most important.
Once you’ve got a project going where you can test the technology out, move on to the sections that you noted earlier and run little experiments.
For instance, with Tekton, I’ll try editing my task from the “getting started” guide to do something more complex - maybe I want it to pull from a git repo and run an installation script. I’ll try it. Then I’ll edit my pipeline to run multiple tasks. The whole time, I’m forming a mental model in my head about what I’m going to use this for.
Run experiments until you either run out of time or feel satisfied that anything else you need to learn can be easily looked up. From here on out, the documentation is a reference.
Application
Congratulations! You’re a documentation-reading wizard. At this point, you can return to your team’s codebase to understand the details of how the technology is used there. And if something looks unfamiliar to you, you know where to read about it.
This is the topic of Part II of Dave Farley’s excellent book “Modern Software Engineering”. You can find the book on Amazon (not an affiliate link)
Loved this thought - it applies equally well to legal reading, except the threshold for stopping would be: read until you recognize the same ideas and concepts repeating. "Run experiments until you either run out of time or feel satisfied that anything else you need to learn can be easily looked up. From here on out, the documentation is a reference."