đź““ 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?