The title of this is a dig at the ‘get smart quick’ scheme peddled by Masterclass.com, but the post itself exists to share the three best pieces of technical writing infotainment that I know. I’ve recommended this stuff to many, many software engineers in the past two years, in 1on1s and during the design docs onboarding session that I used to run at Canva.
Engaging with these three things — a lecture, a podcast, and a website — can create a spark of new perspective on what writing is for and how you can better use it in your work. They won’t make you a good technical writer, for that you merely need hundreds of hours of practice, but they should grab you by the shoulders and push you down a path to better writing and happier readers.
A lecture: Writing beyond the academy, University of Chicago Writing Program
link: youtube.com/watch?v=aFwVf5a3pZM
“The most important thing about your writing is that it be valuable, and I would argue that not only have you not learned how to do this, you’ve learned habits that work against your ability to make your writing valuable.”
You know people who are so keen to have you read something, or play something, or watch something, that they become annoying? That’s me with this lecture.
The lecture is given by Larry McErnerney in the best kind of professory fashion. He’s confident, didactic, dramatic, and passionate. He’s also offering the most exciting kind of lecture: the lecture that tells you “everything you’ve been taught is wrong, but I have here this red pill…”
Watch this, and then keep rewatching until adherence to its edicts is your default setting.
A podcast: Writing, Technically with James Somers
link: signalsandthreads.com/writing-technically/
This episode is from the Signals and Threads podcast, possibly the best software engineering podcast besides On The Metal. In it you spend one hour with James Somers and Ron Minsky exploring the pleasure and the purpose of technical writing.
James Somers is an uncommonly strong combo of writer and programmer. His day job is at Jane Street, and in his spare time he contributes articles to The New Yorker (and The Atlantic).
The host, Jane Street CTO Ron Minsky, brings his typical depth of knowledge and care to the topic, and so the two combine to provide the best discussion of writing in the software industry that I think you’ll find. Writing used to seem like a chore to me, but conversations like this have moved me to start seeing writing as just as enjoyable and worthy as typing out programs in code.
Highlights of this include the discussion of ‘self-documenting’ code, the notion of genre in technical writing, and the episode’s coda, which shares one man’s success using prose to categorize the scale of wind.
A website: The Documentation System
link: documentation.divio.com/
The Grand Unified Theory of Documentation - David Laing
This third piece of the puzzle is likely familiar to you: Divio and their 4-types documentation framework.
To me the core lesson of this framework is that each technical document you write exists to solve a practical problem of a particular reader. As is appropriately hammered home by Larry in the lecture, your writing must be valuable, and solving the problems of others is exactly that.
Documents which aren’t written with an eye on this framework hurt the writer and the reader. For the writer, the selection of a document type narrows you in while creating and makes review and edit more straightforward. For the reader, documentation which breaks down into familiar types is much easier to navigate and digest. As a simple example, the experienced React core contributor is not looking for React tutorials, and the web newbie is not initially looking for React’s API references.
That’s it
Now go and get into them! Enjoy your Masterclass 🍿
