Rendall's blog

Reading the Manual

tech

Reading the Manual #

It took me way too long in my career to understand this, but reading the manual is a relatively easy way to boost programming super-powers.

Some manuals are nice to read ( jest, Redux, TypeScript, Node.js, Testing Library among others ). Some, not so much. Still, nice or confusing, reading the entire manual with focus is low-hanging fruit for understanding your tools.

It is possible to have decent game without reading the manual at all, especially for intuitive programmers, and especially if someone who has read the manual is around to explain things, but why not be that person on your team who has actually read the manual?

Reading the manual is not memorizing the manual, motivated skimming for specific information, nor reading blog posts or watching videos made by people who may or may not have read the manual themselves.

Reading the manual is relaxed intent to understand that which the developers want to communicate directly to you, the user.

How to Read a Technical Manual #

Relaxed, focused and comfortable. The best time to read the manual is any time, but primarily when you feel that you have time. Distraction and anxiety is the enemy of absorption.

Reading the entire manual, once through, makes it easier to skim for specific information when you need it. Searching the manual only for information that is directly relevant to the immediate task at hand can give the false feeling that one has read the manual, but that gained knowledge, while authoritative, is narrow and specific.

Reading technical manuals is a skill like any other, and develops over time. The way to get better at it is to do it more.

An approach #

Reading the manual is for you, so there is no canonically correct way to do it. The correct way is whatever works, which means whatever allows you to best absorb the wisdom that the manual writers wish to impart to you.

That said, if you're having trouble getting started, here's one approach in 8 short steps!

First, identify a manual to read. Perhaps survey the tools that you use most often, whether programming languages, platforms, IDEs, CLIs, version control, OS, whatever. It's best if you have some familiarity already with the topic. Since you're probably here because of TypeScript, consider committing to read the TypeScript language manual. It's straight-forward, well-written, informative and useful.

Second, find the manual. Since it's a technical manual, it's online. You're not usually looking for an API reference, nor a Getting Started, nor tutorials, nor cheat sheets (although, sometimes the manual is in fact hidden there). You're usually looking for a Usage Guide, Handbook, User manual, Reference, Documentation or sometimes Support. On the official TypeScript language site's Documentation page it is called The TypeScript Handbook.

Third, pour yourself a coffee, water, beer or whatever. Get comfortable. Relax. Focus. Begin reading.

Fourth. You might be tempted to skip some parts. Resist this impulse!

For instance, if you were to read the start of The TypeScript Handbook: "Over 20 years after its introduction to the programming community...", what might you imagine the next word to be? What would the introducion be about?

You might, as I did, assume that the next part will be talking about TypeScript, and how much the developers of TypeScript are justifiably proud of their 20 year accomplishment.

The rest of the sentence and paragraph in fact discusses JavaScript, not TypeScript, which is not even mentioned until the end of the second paragraph. This whole section is primarily to impart the information that "The goal of TypeScript is to be a static typechecker for JavaScript programs", what a static typechecker means in this context, and the motivation for the project as a whole. You might already know that, but this particular sentence is a concise explanation from the developers to you about what it is they are doing. Everything else in this well-written manual flows from this. TypeScript can be entirely understood from that single sentence. And you almost skipped it!

Fifth. While I exhort you not to skip or skim, remember that this is for you. If reading the manual linearly from intro to credits doesn't make sense, don't do it. Skip around, read the interesting parts, or the relevant parts. Yes, I know this contradicts Step Four. The idea is to become thoroughly familiar with the material. Do that in the way that you feel is best. It might be relaxing to read those parts with which you feel most familiar already, to see if your assumptions are correct.

Sixth. You did it! Celebrate. Feel that glow of accomplishment. You now have gained a super-power.

Seventh. Use and apply your new knowledge for good. Go through your code and see how you or your team had mistaken assumptions. For instance, after reading in the Jest documenation that "mockReset() does everything that mockClear() does" you can go through and remove all of those mockClear(); mockReset(); statements in your Jest testing suites.

Eighth. Last but not least. Revisit and reread. While absorbing everything is not the goal, becoming familiar is. The more familiar, the more super-power!

Why not read the manual? #

There are excellent reasons for not reading the manual. Personal and professional life is filled with competing distractions. We have to decide among those which are most worth our limited attention. Reading the manual is usually not a pre-requisite for being productive and useful to your team, just as it's not always necessary to read the manual before using an appliance. Sometimes manuals are poorly written, confusing, out-of-date, or just plain do not exist. Even if it is well-written, it may not be relevant. I personally don't have a pressing need to read the Julia language manual today. Maybe tomorrow. I just can't say.

← Home

Leave a comment on this post: