After recently joining NoRedInk and moving to San Francisco, I gave a talk at Elm in the Spring 2019 about exploring one of the larger Elm codebases and paralleled it to exploring a new city. You can find a pdf of my slides here. Enjoy!
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.
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:
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.
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 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.
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:
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.
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.
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 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.
ā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.
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.
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?
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
In college I had my nose to the grindstone with school and work and internships that I was never really a side project type of person. When I get home from work now Iām usually not on the computer ā Iāll watch TV or run or cook or read. Like most people, I probably waste too much time in front of the TV or scrolling through social media. Iām ready for that to change.
Iāve had enough of a break since graduating college and Iām ready to be on the computer learning and building myself as a developer more. I have a friend who always seems to be finding new and cool projects on GitHub and he sends them to me. I was asking him things like āHow do you use GitHub?ā and āHow do you even find these things?ā
I realized my big question was āHow do I make GitHub an interesting place for me?ā
To answer that big question I had to think about what I do find interesting. Iām list oriented so HERE WE GO:
The reason I got into computer science was because I like solving puzzles and CS helps you use those puzzle solving skills in so many different disciplines. It should have been obvious to me: time to find GitHub projects that intersect with my other interests.
Now that I have some starting repos to look into, I need to set aside time to do so. I have two hypotheses for what I think will help me āget GitHubā and be better about working on side projects and exploring the work of other people.
If I scroll through GitHub like I scroll through social media, I will be more inspired to work on personal projects and will find new tech to play with.
Leaving my computer on my dining room table (instead of the ottoman) and listening to podcasts while I eat (at the table, not the couch) will make it easier to get to browsing on the computer after dinner instead of binge watching Netflix.
So wish me luck! Let me know if you find any weird repos on GitHub that you find interesting. Hereās to a summer of inspiration, using my time more effectively, and probably more topics for blog posts š„