Seven Hills I Will Die On

Published on
processslackwords

In honor of Somerville's famous seven hills, here's seven hills I'll happily die on about how to do distributed work at medium-sized companies.

🧵 Practice Slack hygiene

Use threads

Writing related messages into a busy channel at "top level" makes discussions less focused and less useful. For task-oriented channels, use threads to organize conversations. This helps keep more topics visible at a given time.

  • Put screenshots, GIFs, and recreations in threads
  • Consider dividing longer posts so folks can opt in or ignore as they see fit
  • In both cases, leave breadcrumbs making it clear there is more information in the thread
    • "I'll provide more context in thread"
    • "See screenshot / GIF in thread"

Use emojis to represent states

Use emojis to convey useful information (especially on top level messages). This can help folks from having to "unfold" a thread, because they can tell that an issue is solved or pull request is merged.

Examples:

  • 👀 - looking
  • 💬 - commented
  • ✅ - approved (or done)
  • ⛙ - merged
  • 🫡 - will do
  • 📈 - numbers going up
  • Do not write “Wasn't this bug reported in #idiomatic-rustaceans?”
  • Provide actual links, making it drop dead easy to reconstruct context in the future
  • Bug X has happened before, and it will happen again
  • Make it as easy as possible for future you (or a future teammate) to retrace your thinking

It's useful to know at a glance where a link will take you. Linking something as a valuable Javascript resource might not generate the same engagement as linking https://developer.mozilla.org/en-US/docs/Web/JavaScript, because we trust MDN as an authority on web development.

Humans are really good at scanning text - be savvy about when you shorten links (or decide not to).

Use Markdown

Markdown is your friend. Get familiar with what types of formatting are supported by Slack (or your chat program or wiki site). I don't think header tags are supported, but most other things are, including:

code blocks (three backticks to create a block - ```)
  • inline code (single backtick to start and end - `)
  • bolded text (command + b when highlighted, or single star to start and end - *)
  • italicized text (command + i when highlighted, or single underscore to start and end - _)
  • strikethrough text (a single tilde to start and end - ~)

Blockquotes! For big important things. (single right angle bracket to create a block - >)

  1. ordered lists (start with 1., write some content, and then hit shift + enter to get to the next line)
  2. unordered lists (start with a dash -, write some content, and hit shift + enter to get to the next line)

🤖 Standardize your processes

Jobs didn’t want to choose what color turtleneck to wear every morning. I don't want to read 45 different types of pull requests with random formatting based on the time of day, level of caffination, and crafter of the code.

  • Use pull request templates
  • Use conventional commits to make it easy to bisect your own work if you need to find failed tests
    • (And to make it easier for people to reason about "where did functional change happen in the 20 odd commits in this PR)
  • Create runbooks for repeated processes
  • Use version controlled doc software so it's easy to "undo" changes
    • Stop putting runbooks in Google Docs!
    • Use Confluence

Stop wasting your brain cycles on creating a one-off doc for every darn thing. Be lazy.

You should also spend effort to link your work predictably.

You should be able to get from a pull request back to the Jira ticket in a single click, and similarly, from a Jira ticket back to any child pull request.

You should not have to use content search in Jira to intuit what ticket created what pull requests, nor should you have to free type ticket IDs into the URL.

📖 Learn and work in public

Keep a paper trail. The following messages that illuminate thinking make it simple to follow along with what I'm doing "over the wire":

  • "Op, I might have been wrong about that - checking the spec to make sure"
  • "Ah I was wrong - we actually want to specify the expected month in the development planning doc unless we don't expect a project to wrap this month"

Redirect folks to ask questions in public channels. If folks are direct messaging you to learn about complicated domain logic, or product history, ask them to repeat the question in a public channel. Even if it's the first time you're being asked about onward distribution blocking in NORAM, it likely won't be the last.

Look for patterns. Issues that repeatedly come up and are handled adhoc every time are costly, and need systemic solutions.

  • 3rd time you’ve discussed mocking data for flaky E2E tests?
    • Time to create spike ticket researching alternatives
  • Did solving a debugging issue take 2 days and drag in 8 people across 3 timezones?
    • Update the first place someone looked for the answer
    • (This is hopefully a wiki or a Slack channel)
    • It might be a README.md for developers
    • Link back to Slack discussions for context
    • Link the Slack discussion to the solution for future spelunkers

There is no frustration like running into a problem you've already solved and not having taken any notes. Build context publicly so you can focus on what actually matters (building the product).

🕵️ Look before you ask

Here's a little graph that builds intuition on when it's worth asking for help:

posting vs

tldraw.com is my favorite whiteboarding tool - even with the festive snowflakes

Feel free to adjust based on your circumstances. If you're onboarding, or sitting next to the coworker who built the homegrown deploy tool, lower your thresholds.

Here's where I usually search before posting:

  • Slack
    • You're going to look silly if someone else has asked the exact same question three messages ago in the same channel.
  • Confluence
    • Domain knowledge lives here, if it's worth documenting outside code
  • GitHub, looking at previous pull requests
    • Git blame is your rude friend, provided folks write pull request descriptions, link Jira tickets, and "motivate" work
  • Consult the Glean
    • YMMV, but so far I've had success with well-worded questions

Build your mental map of “this kind of issue is handled here”. Different teams may put information in different places, and not all tooling is created equally.

For example, if your company has a 900k-commit mono repo, some types of context will be harder (or slower) to build using git blame.

If all else fails…

💪 Push your own car

Imagine two different scenarios:

  1. You are driving along the highway and you see a car stopped on the side of the road. As you slow a bit to drive by, you see someone sitting on the hood, reading a book.
  2. There's still car on the side of the road, but as you slow down and pass by, you see someone simultaneously steering and pushing the car forward. It doesn't look easy, but they're making steady progress.

What's the difference to you as an onlooker between the two?

If Slack is our highway, consider the difference between the following messages:

  • “My OAuth is broken”
  • “I’m trying to use Warp as my VPN, but OAuth isn't working”
  • “I’m using Warp as my VPN, but OAuth isn’t working for me. I tried switching wi-fi networks, and have also searched in Confluence and the #devops channel but found no leads. Can anyone point me towards next steps?”

Make it as easy as possible for folks to jump in and help you. Anticipate what questions folks might ask while trying to help, and answer them upfront.

The same principles apply for pull requests. Prove that what you’ve tried makes sense / works / is as logical as you can manage. Add screenshots and GIFs showing the problem (or solution).

At almost all companies, there will be subject matter experts who can help unstick you (and others) when you run into trouble. Respect their time, and make the steps you're doing to unstick yourself obvious. You might find yourself appreciating similar efforts when folks come to you asking for your help.

😇 Assume best intent

Be kind and assume best intent.

  • You don't know how anyone else's day is going
  • You haven't walked two moons in their shoes
  • You gain nothing by being crabby or snarky

Be approachable and friendly. Take a big breath and put your best foot forward (asynchronously over text).

I have never felt proud or vindicated after being snippy over Slack. I have felt thankful for the times I've been patient and re-explained something, or provided more context than might be strictly necessary.

If an issue is complicated, or folks aren't seeing eye to eye, hop on a call and get on the same page.

➰ Close the loop!

Closing the loop is ultimately about building trust.

The best teams run most smoothly when their members exhibit a high degree of ownership over their work. Folks remove ambiguity instead of letting it grow, leaving no doubt about who has the ball and where they're driving.

This isn't the same thing as being completely self-sufficient - at any reasonably-sized company, work will be broken down by function. I'm not a designer, and though I know my way around Figma, I rely on designers to plan an intuitive and clear interface.

But making those transitions clear helps folks focus on their designated roles, and makes it easier to support each other when complications do come up.

For non-trivial pieces of work, consider answering:

  • In the best case scenario, how will this work proceed?
  • What are backup plans if complexity or risk complicate things or cause a delay?
  • How will we communicate once the work is done?
  • What other work or teams get unblocked?

Folks who handle these questions preemptively and publicly are able to drive with almost complete autonomy. They still tackle work outside their domain, but when they do, it's easy to trust they'll chase down support if they need it and make noise if things get wonky.

Folks who don't communicate the above end up quietly blocked while they struggle to solve things on their own. By obfuscating the state of the work, they make it less clear how the work will (or won't) ship, and less clear how anyone else could help.

It's ok to struggle with work sometimes - we all spend time learning new technologies, absorbing domain context, and (occasionally) adjust to new work patterns.

But by making it clear who owns the progress of "Feature X"1, everyone in Feature X's orbit feels confident about what will happen next.

Be that person! 🦸‍♀️

Your teammates will thank you for stepping up.