Tag: setup for technical writing

Learning to code: redux


Learning to code: redux

A little over a year ago, I wrote here about how I was learning Swift because there are a couple of apps I want to write. I’ve gone through a few courses online, and had started working through an Everyone Can Code book: AP Computer Science Principles with Swift. I was making good progress, had done the data modeling for my “main” app, but then got a little overwhelmed with the idea of actually starting it. Like, how does a n00b sit down and begin writing an app for the first time?

Then came some health issues last fall, and then Christmas, and then this spring the whole world has turned upside down…

So here we are a year later, and I haven’t written my apps, although I’ve been getting cozier with the code needed to modify the functionality in the static site generators we use for work (Jekyll and Hugo) and my Git foo has gotten to be second nature. But the actual proper “learning to code” I had wanted to do has been nagging away at me. So when one of my co-workers posted that Stanford University’s Engineering department was offering a free intro to coding class, Code in Place, I jumped at the chance to sign up.

Fast forward to six weeks later. I was one of 10,000 interested geeks-in-training who got accepted in this massive international experiment of teaching a diverse student base how to code in Python, entirely online.

I attended all the “sessions” – video chat classes, of sorts, consisting of a group of 10 students working under a “section leader” to practice solving various problems with code. I’ve watched 14 recorded lectures via YouTube, led by Stanford instructors, and have worked through all of the slides and code from each lecture. I’ve learned about decomposition, control flow, images, graphics, and animation – in addition to things like variables, expressions, functions, lists, and dictionaries – all the fundamentals to build a solid coding foundation.

My “deliverables” for class have included three assignments, which I uploaded to an autograder to see if they functioned and passed various tests. I also did a “diagnostic” to help determine which concepts I understood thoroughly, and where I needed additional help. (That was supposed to take an hour, but it took me an hour and 40 minutes – but I worked through the whole dang thing, without bothering my husband the experienced web dev for help, until I got it all done and it all worked.)

Now, we’ve arrived at the final week of class, and I’m doing a final project. For this final project, I’m writing an app! Finally. Not one of the apps I had planned to write a year ago; this is a new idea, which is based on a recent experience I had at work and seems well-suited to be a Python project.

Here’s the premise: the technical documentation I write at work contains screenshots. The screenshots are images taken on various pages of our app. When we make changes to the app’s UI, I need to update the screenshots to reflect the new UI. Sometimes that’s easy, like when the User Profile options change, I know I need to update docs around the user profile. But what about things like adding a git provider, or changing the API key, which are options that you get to through the User Profile menu? It might not be obvious to me that I need to update those screenshots in seemingly unrelated sections of the documentation.

For my Code in Place final project, I’ve decided to write an app to solve this issue: a screenshot inventory tool, which can call out to a visual diffing tool, and then return to me a list of screenshots I need to update based on pages that have visual diffs.

So far, I’ve got the screenshot inventory piece working; I can create a list of all the screenshots in my technical documentation, and associate those screenshots with URLs in the app (dictionaries are awesome). I added some fun calculations to tell me how much coverage I’ve got in this screenshot inventory; for example, I’ve got 181 screenshots in my documentation, but have only inventoried 14 of them so far, so roughly 7% of my screenshots have been inventoried. I’ll work toward 100% coverage, because that becomes more important when I get the second piece working: the visual diffing element.

For the visual diffing element, I’m learning how to make API calls to a visual regression tool, Diffy, that can generate visual diffs of pages across environments. So I can have it diff production and staging, for example, and tell me which of the pages that I’m tracking contain changes in staging. Then my app will give me a list of the screenshots associated with that page, so I’ll know which screenshots I need to update when there are changes to the app.

Bonus: the process of making these associations has made me realize there are some nearly duplicate screenshots in my technical docs, which could be streamlined a bit. So hopefully this exercise will help me tighten up my documentation images and maintain fewer assets. Bonus win!

I’m handling a lot of this data storage and processing in JSON. Code in Place didn’t cover writing to files, so I don’t have databases and am trying to keep the scope small enough to finish a final project in a week (while also working a full-time job and prepping my veggie garden for spring). Fortunately, my data storage needs are simple, and JSON lends itself well to API calls, so that helps.

API calls are also out of scope of what we learned in Code in Place, but I’ve documented APIs before and am familiar enough with the basic functionality that I’m hopeful I can get that part working before the final project is due. If not, I’ve got the screenshot inventory part working, and can always keep working toward the visual diffing processing after class is “over.”

At this point, though, I think I can finally check off the box that says: “learning to code.” I’ve written an app that does a thing, and it’s a step beyond the Hello World type stuff I’ve done so far in Swift. I’m enjoying the problem solving; I spend a couple of hours every evening working on code, and go to sleep with code in my head and wake up with problems solved. I might eventually pick up a Python web framework and give it a web UI, or maybe I’ll leave it a command-line tool and change gears back to Swift now that I’ve actually started and written a thing.

Or maybe I’ll go even deeper down the rabbit hole, because learning is fun, and poke the Python/Swift interoperability stuff and give it an iOS app. Why not? The sky’s the limit once you’re well and truly started down the path of programming.

Investing in good equipment

Business Coding Lifestyle Personal Writing

Investing in good equipment

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.