Read the Damn Documentation

It's the Secret to Innovation

Welcome to another edition of the Damn Optimist. We are dangerously close to the 300 subscriber mark. If this newsletter was an NFT, now would be the time to buy. But it’s not. So you can just share and subscribe if you like my stuff and my humor doesn’t offend your sensibilities.

---

In 2013 I was a financial analyst chasing the American dream. Which, as we all know, is to build a SaaS business and then retire to a life of angel investing and tweeting blue-checkmarked opinions at the masses.

But to do that, I had to learn to code. My process will be familiar to many aspiring developers:

1. Take an interactive online course that makes you feel like this coding stuff’s easy

2. Realize none of that shit really helps in the “real world”

3. Try to read the developer documentation; give up

4. Google what you can’t figure out; copy paste answers from Stack Overflow¹

Source

I never became a good developer. Sure I could hack together some things, but I never learned to read the software documentation properly, and over time I ended up relying more and more on the easy path of copying ready-made solutions from the intertubes.

That’s because reading developer documentation is hard. It’s written by developers for developers. It assumes a ton of foundational knowledge. It’s very technical. And the language reads like a graduate dissertation even if you are familiar with the jargon and concepts.

Ah yes. Thanks for the simple example. I get it now.

The problem isn’t usually with the developer documentation. It is with the average person’s (un)willingness to engage with content that isn’t immediately accessible or entertaining.

But as I get to work more and more with smart, creative problem solvers, I am learning that a willingness to read and process hard material, over and over, is a trait shared by practically all of them.

What does reading the documentation actually mean?

Although I am borrowing a term from software development, the concept is broader than that: it is a willingness to tackle a given field’s source of truth. 

Every field of intellectual pursuit has its own version of “documentation”:

• Software development: library/language/API documentation (vs. Stack Overflow)

• Traditional Investing: annual or quarterly reports and analyst call transcripts (vs. Substack and Seeking Alpha)

• Healthcare: peer reviewed articles (vs. articles interpreting them)

• Politics: reading a candidate’s policy positions (vs. relying on sensationalized media)

• Crypto: white papers (vs. Tweets and dudes on discord)

Although… caveat emptor.

It’s obviously not one or the other. I’ve found some of the most prescient and insightful analyses I’ve ever read on Substack newsletters. But I am arguing here for a balanced diet that leans more heavily toward a domain’s source of truth than most of us are used to consuming.

It’s a how much salad we tell our doctor we eat vs. how much salad we actually eat kinda thing.

Why does it matter?

Most of us learned to get through life how we got through school — the easiest way possible. I don’t mean no one studied hard in school. Many did. But we were all taught to study “smart”, too, which came to mean studying only those chunks of knowledge that will be directly relevant for the test. It meant Cliff Notes, Wikipedia and essays of long graduated students.

Once we ourselves graduated, not a lot changed about how we took in the world.

And I get it: life is hard enough. If someone already did the hard work of interpreting Shakespeare (or the equally arcane COVID-19 travel decrees), why waste our precious time doing it all over again? We shouldn’t. 

Unless, that is, we want to make meaningful progress or solve hard problems. Breakthroughs depend, in large part, on our ability to synthesize new solutions from existing knowledge. And the only way to do that reliably is to read the documentation. 

Here’s why:

1. It forces a deep understanding of the fundamentals 

It’s not enough to be generally smart to, for instance, effectively digest the findings of COMPASS Pathways’ recent study on the effect of Psilocybin on Treatment Resistant Depression. Is a 6 point reduction in MADRS score good? How good? What percent of adverse events is acceptable? If you don’t know the fundamentals, you have to rely on others to interpret the results for you. That’s how you end up with some articles referring to this study as the next coming of Moses and others are like excuse me, what.

The good news is that, much like snowboarding, it takes just a few times of feeling like a complete idiot to start picking up the basics. To continue with the example above, I had to google MADRS scores, snooped around for adverse event baselines from other tests and read up on the difference between Treatment-Emergent Adverse Events and Treatment-Emergent Serious Adverse Events.

Doing this once is the equivalent of going down a bunny slope for the first time. As I read more papers in a given domain, the specific leads me to general principles which lead me back to more specifics. This expands my understanding of a field’s knowledge in both breadth and depth. Looking up the Montgomery-Asberg Depression Rating Scale (MADRS) led me to other types of depression assessments, which led me to reading about psychiatric assessments in general, which opened my eyes to assessment methodology, at which point the direction of abstraction reversed and I started learning about alternative psychiatric assessments, and read about another depression questionnaires, and so forth.

Over a few bunny slopes, you start to make out the shape of the fundamentals. And over the next several, you sharpen your understanding of them. After the initial learning curve, maybe you’re not Shaun White but you’re definitely not unstrapping your back boot to get on the chair lift, if you know what I mean.

Or however you define success

2. You form new ideas and conclusions

With our TikTok-sized attention spans, we rarely get the opportunity to think deeply about topics. Through a combination of our social circles and the media we ingest, we mostly pick up the opinions of others — and that’s ok. We can’t possibly develop our own thoughtful perspectives on most things in our lives.

But there are areas where it is worth trying. Those striving to innovate, to build something new, or simply to do well in a knowledge-based job benefit from engaging with the source of truth of their industry if for no other reason than the fact it takes more time to get through source material like academic papers or investor reports. The difficulty of the material forces us to think more about a given topic, and engage with it more deeply, starting with first principles.

Although it may feel like we’re being less “efficient” when we’re doing this, our thinking, our connection-making, our sense-making is on fire. When I’m engaging with a domain’s source material, I’m doing some of the hardest, and therefore highest quality thinking I’ve ever done. This is an essential recipe for forming my own opinions and coming up with new ideas.

I’d simplify the formula thus: new ideas = time spent x existing ideas. Documentation gives us both — it shines a light on the existing ideas in the space (see #1), and it forces us to spend more time engaging with them, giving our brain a larger surface area for the serendipity of problem-solving to play out.

3. It develops curiosity

Mining technical documentation for treasure is easier with a foundational curiosity about the topic. But if you don’t already have it, forcing yourself to engage with your domain’s documentation is a great way to develop it.

Popular culture frames curiosity as something you either have or you don’t. That’s not quite true. I think of curiosity like Faulkner thought of inspiration when he quipped: I only write when inspiration strikes. Fortunately it strikes at nine every morning.

Although to be fair, faced with this guy, inspiration never really had a chance

With a little bit of patience and discipline, reading documentation is a really effective way to nourish the ingredients of curiosity: 

1. It offers problems that are hard, but not so hard that they’re unsolvable

2. It illustrates creative thinking with tangible real-world solutions

3. It forces you to pay attention (most people can’t speed-read a scientific paper)

4. It lets you experience the exhilaration of really internalizing something new (as distinct from just learning something you didn’t know before)

The reason a lot of people don’t cultivate this curiosity is because they get turned off by the initial boring-ness threshold of a given domain’s sources of truth. 

Being willing to deal with this boring-ness, by the way, makes everything else in the domain feel like dessert. In my example, after engaging with psychedelic clinical trial literature, I gobbled up tomes and commentaries on psychedelic therapy like they were raspberry tart. And they were delicious.

4. It improves the quality of our thinking

Every domain has its own methods of developing, testing and thinking about new knowledge. A reliable formula for new knowledge is to combine existing knowledge with stolen paradigms from other domains.

Commentary and articles usually offer outcomes (the TL;DR), which is what we crave. But outcomes and facts are irrelevant absent the logic that got us there. Sure, I could memorize the product of 62 x 89, but if I don’t understand how multiplication works, the actual number is useless.

Documentation offers not only the facts but also the ways in which the facts are derived, either explicitly or implicitly. Reading the original paper on the clinical trials results of a virtual reality video game on kids with ADHD (a real, FDA-approved thing) introduced me to mental models in behavioral health, pediatric care and randomized-controlled trials that you can’t really pick up in a textbook. I learned how experts in those fields think about problems.

In my life as a financial analyst, digesting annual company reports across a variety of industries opened my eyes to the multiplicity of business models, to ways of structuring real, in-the-flesh, not tidy-business-school-case-study companies, of creativity in problem solving — modes of thinking that I carry around in my pencil case to this day and take out whenever I build anything new.

Charlie Munger, Warren Buffet’s business partner (and very wise dude in his own right), put it simply: “The first rule is that you’ve got to have multiple models — because if you just have one or two that you’re using, the nature of human psychology is such that you’ll torture reality so that it fits your models, or at least you’ll think it does.”

Engaging directly with documentation makes you collect these big ideas — or mental models — within different domains over time. It’s like how having a big Pokemon card collection made it easier for the rich kids in school to find the Pokemon that perfectly countered whatever you threw at them and you always lost. You, in this scenario, being a hard problem. Totally not speaking from personal experience.

Here’s an allegory instead of a conclusion

The open secret of the software engineer shortage is that it’s not really a shortage of engineers. It’s a shortage of good engineers. There are plenty of coding bootcamp graduates looking for work, but as every technical hiring manager knows, bootcamps are not a consistent source of good engineers. 

This phenomenon was best explained to me by my friend Sean, who runs a software shop: most bootcamps curate a curriculum and teach students specific ways to do specific things in specific coding languages. In the face of such spoon-feeding, most students don’t learn to read the documentation themselves. Therefore, few learn to think in a way that allows them to overcome the challenges that come with new languages, new libraries or new types of projects.

That’s why the most successful developers are those who, in trying to build something new, are unafraid to deal with the discomfort of taking on the documentation, knowing that is the secret to excellence.

---

Hey! Thanks for reading. What’d you think of this piece?

Loved it | Liked it | Wasn't interested | Not great | Hated it

1. Kind of like Quora except for developers and with actually useful questions and answers