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 size companies.

🧵 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 thread (and mention that you're doing so)
  • Consider abbreviating posts, leaving breadcrumbs into threads
    • "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"

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 - _)

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 test cases in larger comits
  • 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.

📖 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 unless we don't expect a project to wrap this month"
  • 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 write and do that spike ticket
    • Did solving an issue fixing debugging cookies drag in 8 people across 3 timezones, and take 2 days?
      • Update the first place someone looked for the answer
      • This is hopefully a wiki
      • It might be a README.md for developers
      • It's ok to link back to Slack discussions for context
  • Anyone who is idle enough to be judging your paper trail isn’t working as hard as you
    • Ignore the haterz 💅

🕵️ Look before you ask

  • Search Slack
  • Check Confluence
  • Search GitHub and peek at previous pull requests
  • Git blame is your rude friend
  • Consult the Glean

Build your mental map of “this kind of issue is handled here”. Different teams may put infomration in different places, but not all tooling is created equally. If your company has a 900k commit mono repo, some types of context will be harder to build using git bisect and looking for the correct pull request. git blame in the Github UI can fail on larger files with extensive history.

If all else fails…

💪 Push your own car

When asking for help, consider the difference between the following:

  • “My X is broken”
  • “I’m trying to use my X to do Y and it doesn’t work”
  • “I’m using X to do Y but it isn’t working. I tried Z, and searched in A and B 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. This also applies for pull requests - PROVE that what you’ve tried makes sense / works / is as logical based on your current level of caffeination.

🗣️ Read your writing out loud

The best trick I use for editing is to read your writing out loud. This helps catch run-on sentences, paragraphs that are doing too much, and other complications. Rereading can also help focus ideas into paragraphs, blocks, or other hierarchical content. There's no substitute for clear, digestable language.

😇 Assume best intent

Last (and most importantly) be kind!. You don't know how anyone else's day is going, so be approachable and friendly. You gain nothing by being short or crabby with folks. Take a big breath and put your best foot forward (asynchronously over text).

If an issue is complicated, or folks aren't seeing eye to eye, hop on a call and get on the same page. Your coworkers (and future you) will thank you. 🙏🏻