The career-changing art of reading the docs

Every so often I get asked for advice on how to become an AWS Hero.

The specific answer isn't that interesting - "get involved in the community and hope someone nominates you as a Hero" seems to be the process at AWS. I understand that the Microsoft MVP process is a bit more transparent and better prescribed.

But the general question of "how do I become well-respected in my chosen technical specialty" is VERY interesting. Even if you don't have any aspirations to build a public following, there is tremendous career value in becoming the go-to person within your technical niche.

The person who everybody on your team comes to with their toughest question about that language or framework. The person who knows where all the bodies are buried in ActiveDirectory or Typescript or DynamoDB. Those folks have great careers and job security because authoritative knowledge like that is rare.

To some extent, it's rare because wisdom only comes with experience. But I know plenty of engineers who've sat in the same chair for ten years getting the same year of experience ten times. Heck, I've been there myself; I spent a couple of years as an "accidental DBA" who never really learned that much about SQL Server beyond what the daily firefighting required.

I used to spend a lot of time wondering how other people seemed to level up so quickly on new technologies. How do you break through that stagnant cycle of learning and forgetting stuff in bits and pieces, using the same technology for years without ever feeling like an expert?

A few years ago I learned a secret for doing this, a cheat code if you will, from my fellow AWS Hero Jared Short. This is his secret recipe for leveling up in tech:

Read the documentation for one job-relevant technology, cover-to-cover, every week.

I get it, that doesn't sound revolutionary. "RTFM" is literally as old as computing itself. It's the classic kiss-off answer to questions you ought to be able to Google.

And that betrays a key limitation in how a lot of us think about documentation. We think of it tactically, as a resource to query when we have a specific question or encounter a particular error. We use docs to fill in our known unknowns.

That's how you can get stuck for years, say, administering a PostgresSQL cluster and never really becoming that deep of an expert on Postgres. If you only learn something new when the situation demands it, your mental model of Postgres (or whatever) will look like a gradually expanding version of this:

Over time, as you encounter more new use cases for the technology, you'll burn more "never forget" bubbles into the mental model. But you'll still have this heavy sense of unknown unknowns hanging over you, and you'll never be sure if you're really using the optimal approach to solve a new problem.

Instead, Jared's approach is to read docs strategically, preemptively, curiously: as a way to fill in your unknown unknowns. The things you might not encounter in ten years, but that would cost you two days of troubleshooting if you ran into them tomorrow.

Read docs like novels (cover to cover), not like dictionaries (look up the term, cross-reference, and stop). Over time, that strategy will lead to a mental model of your professional domain that looks more like this:

(This is the same benefit you get from studying for certifications, by the way: you're building a mental map of the domain, so you don't have to stumble through the darkness on every new quest.)

On the surface, that sounds simple, but it's far from easy. Here are three common objections people raise when I advise reading docs as a career-advancement strategy:

Back when I was in college, a well-meaning friend convinced me I should read a book on SAP. Forget today -- I couldn't have told you a single thing about SAP ten minutes after finishing that book. I'd never been inside an enterprise, much less understood the problems these ERP integrations I was reading about were supposed to solve. It was like trying to talk to the aliens in the movie Arrival: my brain was the wrong shape.

Likewise, you probably won't get much value out of glancing through docs for a technology you don't use and have no context for.

So do these two things:

1. Focus on docs for technologies you are already using. We've all had that mind-numbing feeling when plowing through some esoteric text that doesn't relate to our daily lives, where you glaze over for three pages and then go, "what did I just read?"

Avoid this by focusing on docs for technologies or languages you've already got a vested stake in - say, because they're on your plate at work or you're trying to build them into a side project.

Encourage active reading and engagement with the information by asking yourself questions like these as you read:

• Did I understand that? (If not, maybe read the section again)
• Does what I just read match my existing mental model of how this technology works? (If not, do I need to go review a different doc and then come back to this?)
• Could this feature or fact help me on my current project?
• If I had known this six months ago, what would I have done differently? ("Chosen a different technology" is a totally acceptable answer!)

Then, 2. Read those docs repeatedly, on a schedule, over and over. Seriously. If you're on a team that's building out centralized CI/CD for Azure, maybe read the part of the Azure DevOps docs on pipelines this week and the part on build agents next week, and when you get to the end, start over. The cloud changes fast. You'll fold in new information at the same time you're reinforcing the old.

Yes, and weeks of work can save you hours of planning. Maybe use some of the time you currently spend injecting "HERE" print statements into your code to figure out why it's not working.

More seriously, it's not a bad idea to block a bit of time on your calendar each day - 30 minutes, even - for targeted doc-reading. You may find it hard to carve that time out of your workday, but defending time and setting expectations with your manager is its own skill, worth practicing. Call the block of time "deep work." It is.

I don't always buy this excuse. The docs might not be that bad; you might just have the wrong expectations.

For example, the AWS documentation gets a terrible rap for being wordy and poorly-organized. And it's maybe even worse than you've heard - if you're trying to look up the name of an IAM action or the syntax of a CLI command, that is.

But as an educational tool that dives deep on the architectural underpinnings and technical limitations of services, the AWS docs are fantastic. They're better than any book you could ever buy about the cloud. (And the Builder's Library is better still.) The AWS docs are designed not just to be referenced, but to be read. Read 'em!

On the other hand, some types of docs like step-by-step tutorials are very much designed to be referenced during hands-on builder time. It may not make sense to spend a lot of time reading those in the abstract. So bring your common sense.

However. There are also plenty of technologies out there where the docs are truly incomplete, out of date, or just plain wrong - many smaller open-source projects, in particular.

Turns out you have another option here, at least for OSS projects: read the source code. Not sure what a module does, what its edge cases are, what the error code means? Read the source code and find out! It might be faster than (and will definitely be at least as accurate as) looking for the answer in the docs, even if the docs are pretty good.

If you write code for a living, reading other people's shipped, battle-tested code -- not just PRs from your own team -- is genuinely one of the most transformative things you can do for your career. Because while you're answering your immediate question, you'll also be picking up style, organization, and technique from professional programmers operating under all kinds of interesting constraints. Seriously. Read code.

(And then, if it's open-source, maybe consider contributing some docs!)

If you read a targeted set of docs consistently over a sustained period -- say, a couple of years -- while actively practicing on that technology, you will be able to perform magic. That's a promise.

Let's go back to Jared Short again for an example. (Yes, I checked with Jared, he graciously agreed to let me spill his secrets in this piece.) As an engineer at an AWS shop, Jared ...

• Reads the documentation for one AWS service, cover to cover, every week.
• Blocks daily time for this on his calendar.
• Focuses on services he's actually using at work (he tells me that so far in 2021, he's been through all the docs for Lambda, AppSync, and Step Functions).

Jared's been doing this week in, week out, for *years*. And that unglamorous commitment lets him perform nerd magic like this:

If you don't want to take the time to read that whole Twitter thread, let me sum it up for you.

1. An experienced AWS engineer encounters a weird behavior: AWS Lambda seems to be executing code when it should not be. He posts a plea for help on Twitter.
2. Other experienced engineers take a look and go, "huh. Weird." To be clear, this is not a case of RTFM. The problem is nontrivial and the solution, if there is one, is not well-known. Somebody starts tagging in AWS employees for advice.
3. Jared waltzes in and immediately suggests an answer: Lambda is tripping an error during its startup sequence and resetting the execution environment. Jared guesses this even though he's never encountered that specific situation, because he has internalized a passing reference in the docs for Lambda Extensions - a totally different feature - and intuited that the underlying behavior must be the same.
4. AWS employees confirm that Jared is right.
5. The legend of Jared grows slightly bigger. Guess who's gonna get tagged instead of the AWS employees next time there's a weird Lambda problem?

That's how you become an AWS Hero, folks. Or at least a hero on your engineering team. It's how go from developing cloud skills, to leveling up, being known, getting paid, and getting promoted.

Don't wait for knowledge to find you through years of inefficient trial and error. Go get it. And the most convenient, comprehensive place to grab it was there in front of you all along.

Read the docs.