Docs Readability Scoring
In which I automate readability scoring for documentation.
A younger, more innocent me bought a 13" mid-2014 MacBook Pro on closeout in early 2015. My main tasks for my computer at that time were writing documents in word processors (Pages) and using CMSs to create and publish content. I thought I might do some light video editing of travel videos for Corporate Runaways, but didn’t have much need or desire for a powerhouse machine. I had an external monitor for additional screen real estate, and mostly used the laptop screen for reference material.
Fast forward to 2019. In the past few years, I’ve started doing docs-as-code in conjunction with a few open source projects. From the open source project side, this has involved setting up local development environments on my machine, and running apps locally so I can document them. From the documentation side, this has involved using static site generators to create doc sites from files (markdown, mostly). My work needs have definitely gotten more intensive.
Then, this spring, I dove into Swift. When I decided to learn to code so I could write an app I want to use, I took a gradual approach. I worked through some Swift Playgrounds stuff on my iPad, and then read a book or two about coding and Swift. I brainstormed the data structure for my app, and made UML diagrams. Eventually, I took a couple of online classes on Xcode and Swift.
Between my technical writing work and my app development, my 13" laptop + external monitor had begun to feel cramped. What had once felt sufficient for doing marketing writing in a single window, with maybe a reference window alongside, had now become a nightmare of overlapping windows and constant swapping. I wanted more screen real estate so I could have multiple windows open for reference and working simultaneously, and I wanted those windows to be bigger.
But mostly, I wanted Xcode to not just laugh at me when I attempted to compile things, or - even worse - not have Xcode sputter when I attempt to Auto Run a Playground so I can see how things are working as I code.
One of the classes I took involved working in Playground files on my machine as I followed the instructor’s videos. I had to keep pausing the instruction video to wait for my local Playground to respond to my inputs, while the instructor did the exact same thing in the video and then happily chugged along with his much more powerful machine.
It was clear. Xcode was a memory/processor hog, and I had too little of both. I’d been bumping up against those limits for a while now with my other work, but the app development pushed me over the edge. So it was time… time to upgrade my equipment.
(Don’t get me wrong - that little 13" mid-2014 MBP did well to get me into mid-2019 without a hitch, and is still chugging along happily with less intensive tasks; it’s my “couch computer” now.)
I looked around at the options. I could get a newer, more powerful MacBook Pro. But I’d still have limited screen real estate, and that was chafing more and more. Also, I essentially never use my laptop as a laptop these days; I work exclusively at my desk, with my Kinesis Advantage2 keyboard and my external monitor setup. Could it be time to go back to a desktop, when I still remembered fondly the liberating joy of going from a PC tower to my first laptop back in the mid-2000s? It seemed like such a step back, it was hard to fathom.
But the more I thought about it, the more it seemed to make sense to get a desktop again. I never use the laptop as a laptop. I could get better CPU/more RAM significantly cheaper with a desktop. And then I could have another big monitor, giving me the screen real estate I’ve been craving.
I decided to go back to a desktop. I clearly didn’t need a powerhouse like the newly-announced Mac Pro, so I wasn’t going that route. I looked at the Mac mini; a capable little machine. I looked at the iMac, with its beautiful monitor. I looked at the iMac Pro - nope, that’s more than I need.
Waffle. Research external monitors. Waffle. Spec out both machines to a level that would support my current needs, plus some future-proofing. Cringe at the price tag. Waffle some more. Deal with some stupid imposter BS because my husband is the experienced web dev, and how could I justify spending that much on a setup for my less-intensive work + dabbling in Swift development; an entirely self-driven project that may never make me a penny?
Eventually, I drove the hour to the nearest Apple store to see an iMac in person. And then I sat myself down and gave myself a pep talk about giving myself permission to invest in my skill development. Maybe I’ll get more heavily into coding as a tech writer. Maybe I’ll love developing in Swift so much that I’ll pivot to Mac app development. Or maybe I’ll write this app, but then decide that coding isn’t something I want to pursue beyond that. I won’t know unless I give myself the room to develop those skills and see what happens, but it is 100% OK to invest in my career potential.
So I pulled the trigger, and got a beautiful 27" iMac. And it isn’t the entry-level iMac, either; it’s closer to the top tier, to give myself room for growth.
And you know what? It is frigging delightful. It’s so fast. And the screen is so beautiful. It’s a little painful to use it right next to my old external monitor, which isn’t even 4k; the resolution drop and seeing visible pixels is a little jarring looking back and forth. I expect I’ll upgrade that, too, soon. But my tech writing work has been much more hassle-free with the extra screen real estate, and staring at text on a retina-resolution screen is delightfully enjoyable.
So here’s a reminder, if you need one, too: investing in good equipment is an important part of taking your professional life seriously. This is mission critical for remote workers who don’t have office-supplied equipment. I see a lot of remote workers sitting on their couch and typing on a laptop keyboard; that’s a good way to ruin your hands, your back, your posture, and reduce your efficiency and output. (Trust me, that’s how I started out with my remote work back in 2007.)
Yes, I am extremely privileged to be able to spend the money on an Apple device; I know you pay a big premium for their products. And I know that not everyone has the financial freedom to invest in big, splashy monitors and professional-quality office equipment; especially for folks who are the sole breadwinners, or supporting family members. But it is worthwhile to put money aside and invest in the equipment you need for your career, in whatever form you’re able and whatever that equipment looks like for you.
I am very much enjoying my new setup.