šŸ“ A Tale of Two Strategies

In April 2019 I gave my first conference talk at Elm in the Spring. I spoke about being in a brand new code base at the same time as a brand new city and showed that exploring one is similar to exploring the other.

In the past I gave smaller scale talks — a handful internally and one at a meetup. Those were all written in a very similar way:

  • Write everything like a blog post
  • Make slides based on the pseudo blog post
  • Talk to the slides, practicing ~3 times
  • Give the talk

This strategy resulted in fine talks but, for a conference, I wanted to do better. I wanted to put my heart into it and really work with some semblance of a strategy. I’m glad I did because it paid off. By creating with more intention, I gave a talk I was really proud to give.

I started my talk writing process by researching how to write a talk. I reached out to coworkers, friends, and the internet, to see what advice I could find. Through that research, two posts really spoke to me.

Like a pendulum, I tried both sides and wound up somewhere in the middle.

Talking to think

Bernhardt’s How to Prepare a Talk inspired me with the idea of talking (instead of writing) your talk. It preaches creating an outline organically by free talking and adding slides as ideas come up. The idea is that you run your talk every day and see how it changes and solidifies. When I work on a blog post, I usually start by free writing so the idea of free talking really resonated with me.

The very first day I started by grabbing a glass of water, finding an audio recording app, and setting a 45 minute timer. I made sure to follow the rule of free writing: just keep writing (well, talking) — it didn’t matter what I said as long as I kept talking.

On the other side of about 40 minutes of loose associations was where my idea waited for me. Through this free talk process I found the core metaphor for my talk: exploring a new city. I had just moved this year so that was that — I had an angle. I had my narrative.

I tried free talking a few more times but realized it wasn’t a silver bullet strategy for me (big surprise). Each time I spoke, my talk got shorter and shorter because I wanted The Talkā„¢ already. I realized I liked having content I could directly edit and see. I needed a physical artifact I could tinker with and for me that is writing.

Writing to think

Reinhard’s How to prepare and write a tech conference talk had me write it all out. By getting a feeling for how fast you talk you can calculate the number of words you need to aim for — between your outline and research notes, you can use this to gauge when you have enough.

When I first read How to prepare and write a tech conference talk, I was struck by how much writing it was. I was afraid to go down that path because I didn’t want to write a ton of content that I ended up ā€œnot usingā€ because I knew ultimately I wanted to do the talk naturally. After the free talking strategy, I realized that the goal of the word guideline was to recommend an amount of content, rather than writing a talk of an exact wording.

While experimenting with free talking, one of my problems was not having any idea how long to speak on a certain subject. By giving myself a word count for the whole talk, I could figure out how long each section should be, and then focus on just one section at a time.

Apparently I speak around 158 words per minute. Subtracting 10, as recommended by this blog post, and multiplying by 30 minutes gives me 4,440 words. That felt very intimidating at first but I kept breaking it down. If my intro and conclusion took about 10 minutes together, then that left me with 2,960 words. Okay, that’s still a lot. Broken down into four sections? 740 words each! I’ve written essays longer than that before! My new goal became writing one mini-essay a day.

The essays were key for me because that meant each session I only focused on one topic and by writing it out, I could pause and research and look back through my notes and tie things together. Initially I wrote the essays as if they were completely independent. Once they were all produced, I started reading them out loud together to see how they flowed.

Index cards to think

While working out transitions between sections in a coffee shop one day, I saw things from a whole new light: while I had been so focused on my ā€œfinding your way aroundā€ metaphor from a psychology perspective, I realized that I explored code and a city with inverse strategies. This changed my angle. However, by this point I had been writing and practicing my talk in its current form for a week and a half. I was teetering on the edge of the sunken cost fallacy and needed to take a step back.

I went home and pulled out the index cards. I wrote out each step I took to explore my new city on its own card and then sorted the notecards in order of how I explored. Then I turned my back on that pile (yes literally, I didn’t want to be biased by what was in front of me) and created a separate pile of how I explored my new code base and then ordered those.

When I brought the two piles together, I realized that they were, in fact, inverted versions of each other. On another set of index cards, I wrote an example of exploring the code for each step — some I already wrote about and some I hadn’t.

This process gave me the narrative structure of my talk as well as a visual structure. I was worried that I was changing the talk too much with ā€œonlyā€ three weeks to go, but I realized that wasn’t true — I already wrote the majority of my content. All of the additional content came from personal experience. I was just reorganizing things. After my index card exercise, my talk did get shorter but was easier to flesh out and the flow of the talk made more sense.

Once I practiced with my deck of notecards enough times, I made a second set to mock my slides. I have found going straight to the slide deck software to be too detailed too fast so I like to start with this low fidelity version. It also lets me rearrange the slides while running through the talk without having to touch a computer and wait for things to load.

With the technical details, I’m pretty visual. While the index cards worked well for me to get a general idea they resulted in short talk times since I had no code to actually talk about. The final bits of my talk came together once I created slides and added code and screenshots to talk about. Finally putting my thoughts into a real slide deck and iterating on them really helped me solidify the content of my presentation.

Overall

Like Bernhardt suggested, I aimed to talk my talk once a day. While that doesn’t mean that I actually did speak once a day, it means I got pretty darn close.

I recorded myself speaking most times and tried to listen to it the next day while taking notes. The most effective use case was listening to my talk while going through my slides and making sure that everything I talked about got highlighted and that the presentation flowed consistently.

I started writing my talk two months before the conference, including researching how to give a talk. Two weeks before the talk was when I started getting really nervous and stressed and that caused me to work really hard. At this point I definitely doubted if I was going to be ready and if it would all be worth it.

Stress working was not great for my sleep schedule, but it did mean that I got my slide deck finalized (enough) pretty quickly so the week before my talk, all I had to do was one run a day and minor edits. That was very nice.

In that last week I scheduled time in my work calendar to give my talk and grabbed people to listen and give me feedback. This was great because it turns out that after practicing with a cat as my audience for about a month straight, I forgot I had jokes.

As far as nerves on the day of the conference went, having ran my talk as much as I had meant I wasn’t as nervous as I thought I’d be. The nerves hit me an hour before my talk (ā€œwill I throw up?ā€) and lasted about 30 minutes. Then they dissolved into excitement and my heart song revealed itself: Space Jam. When I was done giving my talk, I had so many endorphins pumping — it was honestly hard to focus. I had done it! I had given my first conference talk!

Was it all worth it? Absolutely.

šŸ•µšŸ¼ā€ā™€ļø The Case of the Missing Packages

Onboarding: follow the instructions and most developers will get set up. But me? I’m not most developers. I’m Katie Hughes and I’m the private eye whose setup always goes awry. That is, until my bad luck met its match: a package manager by the name of Nix.

Friday

It’s the end of my first week and I need to do my third developer environment set up — this time on a loaner machine. Aware there will be a fourth round once my computer is back from repair, I sit with my fresh user and consider what I know:

  • There’s a group of people at my company who use Nix.
  • Nix is a package manager.
  • Our main app is mostly set up to use it and could use more developers testing the workflow.
  • I have nothing to lose in terms of my dev set up since I will have to do it all over again with my repaired computer.

The last point was the most important. Whatever I do on this machine will not matter. My luck is rotten when it comes to setting things up but with another try around the corner, it’s time to tempt fate.

I started by asking around — my connections only had brief run-ins with Nix. ā€œThe DSL was what kept me from diving in.ā€ Interesting. I had to ask myself, Have I ever been impeded by a DSL when using a package manager.

What makes Nix so special? What makes its DSL so special? Why haven’t I had issues with DSLs and package managers before? What package managers have I used? What even is a package manager?

Wait. I’m spiraling. I know what a package manager is. I ask the follow up, ā€œWhy has the DSL been a blocker?ā€

The answer becomes a theme for my Nix experience: ā€œWhen I tried it out, a lot of packages were missing.ā€

This answer checks out — the DSL is a blocker if one were to add missing packages. I decide to go for it and start the Nix set up. I install the package manager and run make bootstrap to set up our application’s Nix environment and… an error. I try a different order of things. Same result. I then realize I have one very important skill I wasn’t using: I could try reading the error message. It’s failing around some Python script due to not finding Python.

My understanding of Nix falters — didn’t it install everything you need and just work perfectly? Am I really already having issues? Debug, debug, debug.

No. The setup is wrong. It’s assuming I have Python 3 installed, which people install at some point but I have yet to. A missing package on my system. I work with my partner to make Nix call the Python script within the nix-shell so it would have a more self reliant setup.

In order to run the script within Nix, we preface it with nix-shell and give it a shell config. I make a mental note and my first incorrect assumption: I’ll need to call nix-shell whenever I want to use nix.

Friday comes to an end and I’m feeling pretty good about my first day with Nix. I debugged my heart out and got a pull request into our setup. I contributed. I’m told second hand to install MySQL and Redis through Brew since we want to run those with brew-services. I take the note, stick a pin in it, and leave for the weekend.

Saturday

Like chewed gum on the sole of a shoe, Nix was stuck on my brain. Why doesn’t Nix have something like brew-services? Surely that’s a common use case, isn’t it?

I consult a third party. It’s described to me that Brew only worries about macOS so it knows how to edit the startup scripts to include Redis and MySQL. Nix is agnostic but currently sides with systemd over launchd. This sticky situation can be solved though, but will require further research. Another time, another place. I let this investigation rest for the weekend — I move on.

Monday

Monday comes and I’m pairing… but not finished with set up. I realize there are a few update scripts listed as a footnote on the Nix page that I need to run. While updating, we find that gnutime is an uninstalled dependency. The missing packages increase; I need to install using Brew. I scribble a note to myself to mention that lead in our Nix channel.

My incorrect assumption from before is corrected. It’s clear to me now that the Python scripted needed nix-shell because the Nix environment wasn’t set up yet. But once make bootstrap was complete, I was able to call commands and Nix knew to use whatever was local to the project first. Just like my old pal, npm.

Tuesday

My new machine comes and it’s time for my fourth and hopefully final set up. I’m confronted with the question: do I really trust this Nix character? Or am I just drawn in by the enticing green light of that which is functional programming?

I pull out my notebook and draw up an good ol’ fashioned pros and cons list:

Pros

  • I’ll get the same packages as everyone else.
  • Within my company, the Nix users are growing.
  • I can’t mess up because Nix doesn’t destructively uninstall anything so it is always safe to uninstall and reinstall.

Cons

  • Some packages remain missing and will remain missing until me or another Nix Detective steps in.

The choice is right in front of me and I take it; I choose Nix. In fact, I take it even farther: I decide to go Nix-First. If there is a package I need, I look it up in Nix. I take note of what isn’t there, use Brew, and move on.

Today

I am not investing too much into what is or isn’t ā€œthe Nix wayā€ but I am using Nix. I see its usefulness on a project where many different developers are working on different machines and all want the same set up.

Have I made the switch at home though? No dice. To me, a singular person who sometimes does side projects but mostly doesn’t, I have yet to see the argument that pulls me. So at work I will use Nix and while at home I will stick with my Brew… for now.

šŸ““ Writing for Intern Katie

This was written for my former employer’s tech blog, formally known as AppNexus, currently known as Xandr. You can find the orignal post on their Medium blog here.

Right now I’m Katie, a software engineer who has been at AppNexus for two years. The past me was Intern Katie and I write for her.

Intern Katie is a self-starting perfectionist

Intern Katie is on her second six month internship while working on her computer science degree. Most of her classes were in C and she taught herself JavaScript. She’s the type of person who will follow documentation to the letter and will still wind up being the edge case with set up issues.

Intern Katie is a sponge for knowledge and will search the internet, internal wikis, and slack history to do her due diligence before reaching out with questions. Part of that comes from imposter syndrome and worrying about asking ā€œdumb questionsā€ — she wants to make sure she looks as informed as possible.

It’s important for me to always remember who Intern Katie is so I can empathize with her. Developers come from different backgrounds so I can’t relate to every situation but I can understand their emotions the first time they set up their dev environment, they are on pager duty, or they release to prod.

By knowing what my emotional context was, I’m able to strengthen the documentation I write for other developers.

Remembering my emotional context

ā€œWriting for Intern Katieā€ is shorthand for writing with emotional intelligence, empathy, or emotional context in mind.

This is a technique I use as a developer writing internal documentation for other developers. By remembering what it was like for me, I’m able to understand at least a possibility of the reader’s mentality in the moment.

Take pager duty documentation for example: if you’re writing a collection of all possible issues that can crop up for your application and how to fix them, think back to when you were first fixing those issues and how you felt. I know I felt extremely nervous, scared, and probably tired (if it’s a late night page).

Because I can evoke the memory of that emotional context, I can tailor my documentation. I was tired, so I should write in a very clear way. I was nervous, so I should be extremely detailed. I was scared so I should be kind and maybe add in a comment saying, ā€œThis may seem weird but I promise it is what you should do and you’re doing greatā€.

Emotional intelligence is about being aware of what your emotions are in the moment, remembering them later, and knowing that the next person reading your documentation will likely have a similar emotional context.

You know what happens when you assume

Documentation doesn’t need to be dry — I love writing with a voice that uses both humor and kindness to relieve whatever tension the reader may have. While writing documentation for developers, here are some guidelines I’ve found to be helpful:

  • When describing settings, use screenshots or video grabs as well as a written description. This caters to different learning styles and accessibility needs. It also gives the reader the whole context instead of making them guess at defaults.

  • Write documentation as soon as possible. It’s easier to remember what it was like when your emotional context is fresh (but maybe wait until you’re in a mental state suitable for writing).

  • Document EVERYTHING — as soon as you answer a question you had, document it. Have an unanswered question? Document that too — someone will hopefully fill in the answer! Chances are that someone else will have the same question as you.

  • Write with kindness! An extra step that gives the reader encouragement may help at a time of self-doubt for the reader.

  • If anything could come off as weird, acknowledge it so the reader isn’t wondering if they’re doing things wrong.

  • Follow the ā€œBoy Scout Ruleā€ — leave the documentation better than you found it. If things were wrong, fix them. If things weren’t clear, fix them. This especially goes for people using the documentation the first time! You’re the person it was written for so you know what you needed.

I want to avoid becoming an information silo by spreading my knowledge in a welcoming way. Intern Katie should not need Software Engineer Katie for help; she should feel confident that she’s doing things correctly. She should also feel empowered to fix or add to documentation when she finds a mismatch.

Don’t make assumptions about your reader, don’t put them in a position of making assumptions about what you wrote, and write with a kind voice.

Find your Intern Katie

Do you remember who you were at the start of your career? What did you need? How was your first time on pager duty? Try your best to remember and really embody whatever emotions you went through. That’s how I write for Intern Katie — by remembering what it was like and feeling those feelings again.

Writing with emotional intelligence helps build a kind and humble community by having your developers at any level interact with approachable and accepting documentation. Write for your past self and clear, detailed, encouraging documentation should follow.

So, who’s your Intern Katie and how can you help them?

Helpful Resources

🧽 In Memes We Rust

This may seem like a familiar scenario:

  • My friend says a comedically judgmental thing on Slack.

  • We all respond with an emoji representing the Mocking SpongeBob meme.

  • I try retyping their message, alternating case.

  • It’s a pain.

That was all it took to add a new item to my ā€œlearning project ideasā€ list: spongemock CLI. It’s simple enough to be done in one sitting but is dumb and frivolous enough where I find it fun and interesting.

Is it unique? No, of course not. Does that mean I shouldn’t do it? No, of course not!

I had been wanting to learn Rust for a while but never made it a priority. It seemed really fun! People I admire were learning it! I should learn it! So I did.

I had a week off and while I was just lounging around a house in the high desert of Oregon, sipping gin and tonics, I decided it was time to learn Rust (and work on that silly spongemock idea I had).

I found The Rust Programming Language Book (apparently called ā€œthe bookā€ according to at least the rust lang documentation page) and immediately enjoyed how well written it was. In college, I majored in computer science and minored in psychology and the quality of textbooks was day and night: psychology books just got how people learned in a way computer science books didn’t.

The way the Rust book was formatted reminded me of those psych textbooks — it was cognizant of how people (specifically, its intended audience of engineers) learn. There’s some basic getting started but it immediately dives into a project and explains things enough as you work on it. Then it goes into details of how things work until it’s time for another project.

I decided that after the project in chapter 2, I would start working on my spongemock program and just see what I can do.

Chapter 2 gave me a really solid foundation: some input, some output, a little looping — great! I filled in the gaps I needed to complete a basic spongemock by searching for it myself. A lot of those gaps were around string and character manipulation. The way Rust handles strings and characters reminded me of C (what I mostly did in college) more than anything I’ve done in a while.

This strategy of information gathering got me pretty far! I could ask for input and mock it by alternating case for letters only, leaving alone any other character.

I mean honestly that’s the heart of spongemock. But I started dreaming up ideas! For example: making it more of a CLI than cargo run and taking command line input (it does now!) and maybe even having flags and reading from files. That’s when I started having a harder time understanding what I was finding online.

BUT GUESS WHAT: the book is so well formatted and teaches a command line program with file I/O as chapter 12.

I’ve decided that this project will be a work in progress as I go through the book. It was a good learning project because I could do it in one sitting and knock out what I needed for basic functionality. It was also a good learning project because it can grow as I learn:

  • As I learn better practices

  • As I learn file I/O

  • As I learn more about building a CLI

  • As I learn more about being a Rust programmer!

I wish my operating systems education had been less judgmental. Rust seems like a good community to relearn systems in a healthier way. I like this project because it is small, bite sized, and not serious at all. I saw a tiny itch and scratched it without worrying about if it had been built (it has) or if I was doing it right (probably not).

Best practices and unique ideas come in time and practice, they don’t have to be the priority when you start learning.

I loved getting to be a creative investigator where my only goal was a silly program for the sake of learning and I’m excited to continue down that path with the book and spongemock. I certainly will be keeping my eye out for more small joke ideas that get me excited about learning because that’s what really matters.

Want to check out my project? https://github.com/glitteringkatie/spongemock