My sudden urge to wax poetic on this topic arose after discovering an intriguing quirk within a util nestled deeply within Vue 3’s source. Let’s dive right in — take a gander at this slighly-adapted version of the default Vue "Single-File-Component" demo:

<script setup>
import { ref } from 'vue'

const msg = ref('Hello World!');
const isFriendly = ref(true);

Object.prototype.enemy = true;
</script>

<template>
  <h1 :class="{ friend: isFriendly }">{{ msg }}</h1>
  <input v-model="msg">
</template>

<style>
  .friend { color: blue; }
  .enemy { color: red; }
</style>

The result (as of Jan 4 '25):

---

Why is the text red?

export function normalizeClass(value: unknown): string {
  let res = ''
  if (isString(value)) {
    res = value
  } else if (isArray(value)) {
    for (let i = 0; i < value.length; i++) {
      const normalized = normalizeClass(value[i])
      if (normalized) {
        res += normalized + ' '
      }
    }
  } else if (isObject(value)) {
    for (const name in value) {
      if (value[name]) {
        res += name + ' '
      }
    }
  }
  return res.trim()
}

const arr = ["x", "y", "z"];
const obj = {a: "x", b: "y", c: "z"};

// Loop over array by index:
for (let idx = 0; idx++ idx < arr.length) { console.log(arr[idx]); }
OUTPUT >>> x y z    // with newlines between each item of output

// Loop over object by index:
const keys = Object.keys(obj);
for (let idx = 0; idx++ idx < keys) { console.log(obj[keys[idx]]); }
OUTPUT >>> x y z

// Loop over array by key (array key ARE indices):
for (const key in arr) { console.log(arr[key]); }
OUTPUT >>> x y z

// Loop over object by key:
for (const key in obj) { console.log(obj[key]); }
OUTPUT >>> x y z

// Loop over array by value:
for (const val of arr) { console.log(val); }
OUTPUT >>> x y z

// Loop over object by value:
for (const val of Object.values(obj)) { console.log(val); }
OUTPUT >>> x y z

Object.prototype.enemy = true;

// for-in will iterate over not just keys of the object,
// but ALSO keys in that object's prototype:
for (const key in obj) { console.log(obj[key]); }
OUTPUT >>> x y z enemy

// for-of will ONLY iterate over values that exist directly on the object:
for (const val of Object.values(obj)) { console.log(val); }
OUTPUT >>> x y z

We each have our own methods that operate behind-the-scenes while we engage in the process of software development. I like to think of this as the "craft." A woodworker hand-shapes chisels, constructs planers custom-fit to their own hands. A painter thoughtfully composes their pallet and designs a color-mixing strategy that suits their visual style.

We as conjurers of software are lucky to count ourselves in this group — we have the power to build our own tools (and far more efficiently than a hand-carved plane, at that!). Exploring this power can be incredibly satisfying, and creatively enriching. It’s a slow process, something that develops over years, and there are no obligations, requirements, deadlines, or endgames — it’s something that happens naturally as we work, and discover new ways of working that click.

The real magic lies in an inevitable fact: we all develop our own unique approaches to the craft, which creates boundless potential for learning from one another.

This post is my first foray into the world of craft-sharing, one lightweight approach that could be utilized or adapted to help in your own process of toolbox construction. Without further ado, here’s how I combine the acts of note-taking and tool-building when I join a company.

Figure 1. A visual representation of my brain on the first day of a new job

I recently began a new engagement with a great startup called Rising Team. They’re building software to help remote creatives like me learn more about each other and the collaborative process, to enrich our relationships and the work we do (they’re also hiring! https://risingteam.com/careers). I’ve learned from prior experiences that orienting myself within a completely new codebase and technology stack can be overwhelming — a feeling that can only be derailed through copious amounts of note-taking.

However, as much as I love paper notes, over the years I’ve become attached to a medium which works even better for me in the "getting ✨ done" department of software development. That format? And please give it a chance — shell scripts.

A Single-File Toolbox

#!/usr/bin/env bash
...
source "$HOME/.bash_risingteam"
...

#!/usr/bin/env bash

function srt() {
  vim "${BASH_SOURCE[0]}"     # BASH_SOURCE refers to the path of the current
  source "${BASH_SOURCE[0]}"  # script file (in this case ~/.bash_risingteam)
}

Tools

function bookmarks() ( set -euo pipefail
  fzf -0 -1 -e --reverse --no-info --height="50%" \
      --tiebreak="begin,length" --query="${1:-}" \
  | awk -F' ' '{print $NF}' \
  | xargs -n 1 open
)

function rto() ( set -euo pipefail
  bookmarks "$@" <<-BOOKMARKS
    prod       https://app.risingteam.com/
    prodadmin  https://app.risingteam.com/admin/
    stage      https://stage.risingteam.com/
    stageadmin https://stage.risingteam.com/admin/
    dev        http://localhost:8080
    devadmin   http://localhost:8080/admin/
    docs       https://github.com/risingteam/kit#readme
    pulls      https://github.com/risingteam/kit/pulls
    branches   https://github.com/risingteam/kit/branches
  BOOKMARKS
)

# note: urls have been modified from originals for clarity/security purposes

fzf \    # invoke fzf
-0 \     # exit immediately if there's no match for query string
-1 \     # select imediately if there's only one match for query string
-e \     # enable 'exact-match', where quoted terms are matched exactly
--reverse \    # closest match at top of list instead of bottom (preference)
--no-info \    # hide superfluous info about list such as count (preference)
--height="50%" \    # make the fzf render area 50% of the current pane height
--tiebreak="begin,length" \    # favor matches earlier in string as top criteria
--query="${1:-}" \             # if called as `rto str`, use "str" as initial query
| awk -F' ' '{print $NF}' \    # after selection, pare down to 2nd part only (URL)
| xargs -n 1 open              # using xargs, pass URL to `open` (in browser)

function rtdb() ( set -euxo pipefail
  psql -h localhost -p 5432 -U evan -d dev-database ${*:+--command} "$*"
)

INPUT >>> rtdb
+ psql -h localhost -p 5432 -U evan -d dev-database
psql (14.2)
Type "help" for help.

dev-database=#

INPUT >>> rtdb \\d user_account
# double-backslash escape is necessary here, unless quoting
+ psql -h localhost -p 5432 -U evan -d dev-database --command '\d user_account
                                        Table "public.user_account"
    Column    |           Type           | Collation | Nullable |
--------------+--------------------------+-----------+----------+----
 id           | integer                  |           | not null |
...

INPUT >>> rtdb
+ psql -h localhost -p 5432 -U evan -d dev-database

# make `rt` command universally available:
export PATH="$PATH:$HOME/risingteam/scripts"

function rts() ( set -euxo pipefail
  local backend="cd ~/risingteam; pipenv run ./scripts/rt server dev"
  local frontend="cd ~/risingteam/frontend; npm start"
  tmex risingteam --reattach -p "${backend}" "${frontend}"
)

function rtk() ( set -euxo pipefail
  tmux kill-session -t risingteam
)

Automate Everything

function rtreset() ( set -euxo pipefail
  rtk &>/dev/null && true
  cd "$HOME/risingteam"
  ./scripts/rt data reset || ./scripts/rt data init
  echo "Enter a password for local risingteam admin user:"
  ./scripts/rt manage rt_createsuperuser --email evan@risingteam.com
  for name in "session_admin" "demo_mode"; do
    rtdb "INSERT INTO waffle_flag (name, superusers, staff, authenticated, testing, rollout, note, languages, created, modified) VALUES ('${name}', TRUE, FALSE, FALSE, FALSE, FALSE, '', '', NOW(), NOW())"
  done
  sleep 10 && open "http://local.rtkit.test:3006/auth/login?next=/get-started/sub/monthly/1" &
  rts
)

for name in "session_admin" "demo_mode"; do
  rtdb "INSERT INTO waffle_flag (name, superusers, staff, authenticated, testing, rollout, note, languages, created, modified) VALUES ('${name}', TRUE, FALSE, FALSE, FALSE, FALSE, '', '', NOW(), NOW())"
done

As I have (somewhat unexpectedly) been drawn into the world of management, one of my favourite parts of the job has been mentoring and uplifting then engineers in my organization. One of the most critical parts of that process is the fitting of incrementally more ambitious and open-ended projects to devs at each step of their learning curve, and the most important part of that, in terms of ensuring their success, is act of writing effective design documents for their projects.

This isn’t a post about why design docs are fundamentally critical to the design of good software (Joel Spolsky articulated that more effectively than I ever will, as have, honestly, many, many others) but it is worth noting that single most common root cause of failure that I’ve seen hamstring projects, particularly those run by more junior engineers, has been inadequately thorough design documents. This is the singular moment during which more senior engineers can scrutinize each element of the design, particularly the nasty and easy to miss failure cases, in the context of the whole (other than, of course, after the project launches and things start breaking). However, the exercise of communicating technical intent, complete and unambiguous, is a new and foreign challenge of its own - and even just getting started can be a daunting task to someone writing their first design doc.

So instead this is a post about what you need to get started writing your first (or your hundredth) design doc, in as brief and functional terms as is possible. With the following, I hope to provide all the structure and tooling you need to create something comprehensive for review from your peers, as well as offering a few tips and tricks to keep in mind as you fill out the format along the way.

Structure

There’s nothing more intimidating, as a writer, than a blank sheet of paper - where do I even start? To that end, for any informative documents I’m required to produce, I start with all the sections and headers I can identify, and turn the problem from “filling out the page” into (as much as is possible) “filling in the blanks.” Although the following may not quite be universal - you shouldn’t shy away from altering it to fit your domain - I find that generally starting with this format gives me enough structure to start breaking down the document into smaller problems to digest.

1. Overview
   1. Stakeholders/key personnel - Start off with who are you (author), who owns the thing you’re building (teams), and who cares about it (key stakeholders). Although this may be unnecessary in some smaller docs, for a broader audience it really helps the folks asking questions if they know who they’re talking to.
   2. Background - This is where you start the narrative. It’s always important to think about how the content of your document flows from section to section, each conveying unique information that supports the conclusions that follow, and this is where you can lay your groundwork for your readers’ comprehension of that narrative. Keep it short, this isn’t the time to justify all the specifics of your solution, but set the stage with the impetus for the feature, and any requisite technological context.
   3. Essential terminology - Although there’s a good chance you can skip this section, take a moment and consider - are there any terms that are specific to this domain that your readers are unlikely to know, or are you introducing novel terminology for the purposes of your solution? I’ve seen countless technical discussions spiral into frustration because speaking unambiguously in english is actually really hard, and anything you can do to preempt potential confusion will save you effort down the line.
   4. Objectives
      1. Goals - What are you going to accomplish?
      2. Non-goals - What are you not trying to accomplish? Don’t put world peace. Many projects have intuitable extensions, or adjacent problem domains that you may be pushed towards rolling into scope. Push back - be clear regarding your boundaries (in documentation as in life).
2. Technical Summary
   1. General Overview - Explain the logic and flow of your solution in two to three paragraphs, or if you’re feeling ambitious, five or six bullet points.
   2. System Diagrams - At least a broad system overview, with diagrams for key subsystems as necessary, with complimentary notes providing context as necessary.
   3. Key Components - Using a new AWS offering? Have a really complicated class heirarchy that’s central to the solution? Offering a new API to internal clients? Enumerate them here.
3. Technical Flows - This is a chance to explain how what you’re building will be used. Whether it’s a library, an API, or elsewise, understanding it through its flows rather than it’s atomic points of interaction is a much more informative lens for critiquing the design. Sequence diagrams are immensely useful here, and I’d strongly recommend getting familiar with them for anyone who writes client-facing code (more on them later).
4. Contracts/API - Okay, so now that we understand the flows, what exactly are our points of contact? The prior segment should have had most of these listed by name, and now that the reader understands how they’ll be used you can step through and give more detail on specific arguments, return values, and encapsulated business logic.
5. Persistence - Are you storing data? Great, now let’s get into the details. How is that data modelled? How is it indexed? Is it scalable, and is it flexible enough to support future use cases? Bad modelling at the persistence level often causes problems down the road - particularly for the second version of a feature as you expand beyond the tightly scoped initial problem domain, so making sure the constraints of your design are well understood at the outset can be enormously valuable.
6. Observability
   1. Metrics - What are you counting?
   2. Monitors - What are you analyzing?
   3. Alerts - What do you want to respond to?
7. Risks and Risk Mitigation - Where could this project go off the rails? What business outcomes or technology constraints might result in failure cases? What might extend the timeline beyond your current estimates for delivery?
8. Deployment/Rollout Strategy - “Turning it on” is another common point of failure for new features. Particularly if your project is a new/alternative flow or resource, ensuring that that any ramp up is smooth and well monitored is essential. How to manage deployments is the subject of another post, but at a minimum cover timelines, rollback plans, backwards compatibility, monitors to track during deployment, and metrics to be used as success criteria.
9. Appendix - At this point you’ve covered your bases! Long form references, or content that isn’t strictly necessary to the pitch but may be useful to a curious reader can be plugged into an appendix, making it clear that this isn’t part of the body of the proposal. You can drop basically anything in here, but a few likely entries follow:
   1. Alternatives - Are there other strategies that are still worth considering, or that you want to justify in their exclusion?
   2. Required Sign-offs - In some cases explicit sign off from a set of technical partners (for inter-service contributions, for example) may be useful to have on paper. Drop it in here!
   3. Follow-on projects - Where are you taking this project post-MVP?
   4. Specific scope exclusions - Any potential expansions on the non-Goals as listed above.
   5. Dependencies - Projects being executed in parallel, requirements of non technical partners, really anything that may block the project from proceeding.

Tools

Of course, not everything you’ll be sticking in that doc will raw text - it’s helpful to have diagrams and tables to present specific structured information, and so I’ve highlighted a few of the most lightweight and useful tools I’ve come to appreciate in my time producing design docs.

Authorship

Where do you actually write the doc? Honestly, “wherever you’re most comfortable” is a good place to start, and the first few hours should mostly be spent dumping as many ideas as possible out of your head and into their respective sections in preparation for organization and editing. That said, once you’ve got a semi-mature draft I strongly recommend finding a buddy, copying the content into a collaborative editor like google docs, and soliciting feedback as early as possible. You don’t have to have every potential question answered and every spelling eror fixed before you start getting criticism, and it’ll save you having to make larger changes when your document is more complete. Is this obvious? Sure. Have most people put off reaching out to peers in favour of adding a little more polish first, to their net detriment? Absolutely.

System diagrams

A high level system overview is near essential for any system describing more than one client and one server. Although you can get by with just Google Draw (or, for that matter, MS Paint), there are better solutions out there. Diagrams.net is free, easy to use (many of the tools in this space are far more complicated than necessary for the general case), and produces diagrams that aren’t an eyesore. If you don’t want to think about what to use here (and you shouldn’t, generally, that’s not the problem you’re trying to solve), just use this. Technically this site addresses almost every use case listed here, but due to my preference for text-based diagramming tools (over wysiwyg), I’ll include more specialized tools in the following sections.

Sequence diagrams

These are the bees knees, and criminally underused. Many technical specifications are most usefully understood through the the flow of data and the sequence of their use, but it can be hard to express these things in raw text without being so verbose as to obfuscate the key information. Sequence diagrams offer a flexible and fun way to render these flows, and in many cases can replace hundreds of words of text with a few easily understood images. I’ve been using websequencediagrams.com for years, and would strongly recommend them for their simplicity and clarity.

Entity Relationship Diagrams

Got a bunch of models, and those models are related to each other? Just like they hammered home in CS101, entity relationship diagrams are your friend. They’re simple and easy to read, so although they can be skipped over in more simply modelled domains, they’re an extremely efficient utility to have in your toolkit when necessary. Diagram.codes has a bevy of diagramming options, is well designed, and it’s ER syntax is particularly clear and simple.

API definitions

For long term documentation I think that APIs should almost always have their docs written inline with their method signatures and docs should be generated from there. However, before the API exists in code, tooling for expressing the contract you’ll be putting in place is a lot more sparse. Most popular options, like Swagger, are a little heavyweight for the brief and high-level definitions that might exist in a design doc, and I haven’t found any solutions that I’ve really loved. As such, I basically just copy and paste a rich-text version of this snippet, and now you can make your own too!

+--------------------+-----------------------------------------------------------------+
| Endpoint Name/Path                                                                   |
+--------------------+-----------------------------------------------------------------+
| Description        | A little about the endpoint, how it operates, and why it exists |
| Arguments:         | | Parameter | Type |            Description            |        |
|                    | | --------- | ---- | --------------------------------- |        |
|                    | |    id     |  int | the uuid of the referenced object |        |
| Response:          | Serialized response object                                      |
+--------------------+-----------------------------------------------------------------+

Techniques

So now you have a structure, a general sense of content, and a few handy tools for mocking up the diagrams that you may want to include - you’re pretty much good to go! Before you rush off though, I’d like to offer a few more points to consider as you draft your first (or fiftieth) design doc.

• Good headers help set expectations for readers and break up your document into easily parsable components. Good formatting seems like a nicety that many developers see as unnecessary frivolity, but self explanatory headers with good visual distinction between h1/h2/h3/etc. make a huge difference for reader comprehension.
• Don’t just cover the happy path. Failure modes are an essential component of a design doc, and warrant equal emphasis along with the success cases.
• The design doc should not be a product doc. Linking to the product doc near the top is a great idea, but retreading product/business outcomes, unless the project is strictly technical (and even then you could pull those out into another doc), is often counterproductive because it invites debate on a tangential subject, rather than focusing attention on the technical design.
• Emphasize complex elements, and unique/novel (within your context) elements, leave explanations of common infrastructure out or note them only briefly.
• This is a long doc structure. It can feel unduly burdensome for smaller projects, and even for larger projects it’s easy for this to feel like busywork once the author feels they’ve fully internalized the solution. Again, I don’t want to litigate that these docs are valuable (they are), but if you do feel like this is too much - do less. Something is better than nothing. Skipping some sections in the name of velocity or flexibility or just in the name of saving your sanity after a long week, can be totally fine so long as the doc still covers the core design elements of your solution. Edit the format to fit your needs and your patience, but remember the more thorough the doc, the more detailed feedback you’ll get from your peers, and the more value it will return to the project.

Finally, one last note before you go - this guide is intended to inform a formal proposal of a solution, which may be several docs deep in the design process already. You might write out a complete list of approaches to be debated, early on after identifying a problem space; you might throw together a one-pager outlining your preferred solution when you’re first seeking approval from your peers or boss to explore the direction; those are good an important, but should not be as exhaustive as the document outlined above. A design doc should assume an opinionated position regarding the correct solution, and justify that opinion through its thorough treatment of the problem space. If you’re not ready to tackle the design doc yet, that’s okay! Seek advice from peers or mentors, do a lightweight comparison of alternative solutions, and make clear to your stakeholders that you need a little more time - this is a big commitment! But when you are ready, I hope this guide helps make your experience of writing your design doc just a little bit easier.

Working from home, working distributed

Although an exhaustive analysis is outside the scope of this document, I think it’s constructive to consider our new work circumstances in two dimensions rather than lumping it all together under “remote work.” First, we are now working from home: this means dealing with distractions, new challenges to our work life balance, and other largely environmental complications to our processes. Secondly, we are working distributed, newly remote from our peers and collaborators: this comes with issues of communication and organization, and of staying on top of information that used to be at our literal physical fingertips. I think by considering our new circumstances through this lens we can move beyond listicles of tips and tricks, and instead provide a framework for more deeply understanding our challenges at hand and finding solutions tailored to our individual needs.

Working From Home

Although I’m a fan of and advocate for the many advantages of working from home (notably, no corporate policies against your cat sleeping on your desk), I’m more than happy to acknowledge that it also comes with its fair share of challenges and drawbacks. The loss of enforced boundaries is a common frustration for people newly transitioning to working from home, and somehow it can be simultaneously challenging to avoid the distractions and temptations of the home while also frustrating to find ways to disengage from work and not let it bleed into the rest of your life. Similarly, those new to home offices will find themselves suddenly deprived of the many enriching aspects of office life (as strange as that may sound) that exist at the margins of work and that provide essential social and physical variety to our lives.

Boundaries of Work

Boundaries are going to come in a few different forms but the first, and most obvious, category to address is physical boundaries. Not that you have to build up blockades to keep out your family, but a clear definition of where you work and where you don’t will give you great mileage for both defining to others when you’re in “work mode” and not to be distracted, and also for training your brain to reflexively understand the same and help you find that “flow” that’s so much easier in a dedicated collocated office. Again, maybe you don’t have a home office, or maybe not even a desk, but that doesn’t mean you can’t carve out a dedicated space for thinking and working. Maybe between 9am and 5pm the kitchen table is strictly off limits to non-workers, or maybe for the duration of staying at home you only sit in your comfiest chair when you’re working.

And that nicely brings us to barriers around time—if the table stops being an office at 5pm, then you have to leave that office and go back to real life. It’s so easy to just keep going when you don’t have to physically leave work behind, but by all appearances this is going to be much more of a marathon than a sprint, and making sure that you’re not accidentally burning yourself out is going to be critical to your long term health. The inverse also applies —you should be very cautious about allowing yourself to take on other tasks during your work hours, like tidying up around the house or taking time for video games (not that you shouldn’t at all, just that you should be conservative and deliberate in your choices). If you’re already struggling to remain focused, giving yourself more chances to feel more ‘at home’ rather than ‘at work’ will further cement your mentality of not being singularly focused the way you would be in an office.

Finally, social boundaries play a critical role as well. Those who aren’t working from home—but are home with you—are likely not going to immediately appreciate how important and how hard it is to keep a clear(ish) work-life divide. That doesn’t mean you can’t plan and enjoy moments with the people around you, but if the people around you feel they have unfettered access to your person, it’s on you to have the willpower to say no to them each and every time, and pretty often it’ll be all too easy to say yes. Being clear and up front about the requirements of your job and the times when you’ll be occupied, prevents regular interrupts and distractions and makes the times that you do surprise them with an afternoon break all the more special.

Lost Margins

The other, subtler change you have to account for when you start working from home is the loss of the margins around your work that existed when you were in an office. There’s a significant portion of your day between the moment you leave for work to the time when you get home that isn’t occupied with what would traditionally be considered ‘work,’ and while much of that time is spent on things that are frustrating and unnecessary (I’m looking at you, commute), there are significant segments that are remarkably critical to our health and happiness. The first thing that you may notice is that you are significantly less active than you were before. Although office activities aren’t exactly a rigorous workout, the bustle of getting to your place of work, shuffling between meetings and events, and running to the bathroom that is for some reason on the opposite side of the building is a lot more active than rolling out of bed and grabbing your laptop (in my experience, the difference between about 3500 and 500 steps a day). If you’re not that active, like me, then you’ve just lost a meaningful percentage of your daily exercise (about 30% if we’re aiming for 10k steps and going by my numbers), and finding a way to replace that is important for staving off sluggishness and fatigue. If you struggle sticking to exercise regimes, I find replacing the lost activity with other ‘movement with purpose’ is easier to maintain; when I’m having a hard time with motivation I’ll allocate an hour in the afternoons for tidying or minor projects around the house. It keeps me moving when I’m not up for going for a run, and has the added bonus of making my home slightly less of a disaster.

Another significant loss in transitioning to working from home is the loss of social contact. You may not chat a lot with your colleagues, you may not even like most of them, but your day was likely still punctuated with casual social interactions that have just disappeared entirely. I’m sure a psychologist could get into a lot more detail about how social deprivation affects us and why humans just aren’t wired for it, but those little moments when you said hello as you rolled into the office, or chatted after a meeting, or paused to catch up in a hallway, those were important. It can be hard to understand at first why something feels off, but in time you’ll likely find just how much you appreciate what little casual social contact you have left. Fostering these connections, and making deliberate time for interactions that previously would have been incidental (I personally favour leaning into casual catch-ups during the start of calls, as we wait for everyone to get on and ready), is a valuable investment in your mental health and, as I’ll cover in the next section, an equally valuable investment in your productivity.

Working Distributed

Working in a distributed manner is likely something that most folks have at least some passing familiarity with, even if they haven’t had to be particularly thoughtful about it before. Any time you’re working with someone who isn’t in the seat right next to you, you’re dealing with some degree of distribution, although for most people this is generally with others with whom they are more professionally distanced, rather than close collaborators. The uniqueness of the current situation comes from the rapid displacement of previously collocated collaborators—people with whom you are expected to be tightly integrated are suddenly inaccessible in ways you likely haven’t had to cope with before. Bridging that gap—making your team as accessible as it is integrated—is fully possible (and the crux of successful distributed organizations), but the transition is extremely jarring when we have an established set of norms that rely on seeing each other in person on a daily basis. Reestablishing Presence

If there’s one thing to focus on when trying to reconnect a team that’s been recently distributed, it’s re-establishing a sense of presence. An enormous component of the accessibility that exists between members of a collocated team is their immediate knowledge of their coworkers location and status. A quick glance can instantly establish whether a team mate is at work, and furthermore whether they’re readily interruptible, based on whether they’re wearing headphones, posture, and many other small cues that are obvious in person. That immediate understanding of the presence of one’s colleagues makes choosing when and how to engage with them about as low friction as possible, as opposed to when they’re on the other side of the internet and it may be hard to establish whether a coworker is even in “the office” that day or not. There are a myriad of ways to communicate presence remotely—status messages in your favourite chat app, announcing your arrival/departure in a public channel, and automated activity trackers that exist in many modern tools (like Slack or Teams)—be considerate of what works for you and your team and make sure that it is used widely and consistently.

Tools and Technology

There’s a whole separate blog post to be written on the best tooling for distributed work, so once again for the sake of brevity I’ll stick to the core concepts and personal highlights as best I can. When it comes to sharing information you’re generally going to have tooling that fits into three categories: synchronous communication (video/phone calls), asynchronous communication (chat/email), and information repositories (Jira/Google Docs); and broadly these map to three different modes of exchange: freeform exploration/debate, structured discussion, and the establishment of a referenceable library of information. The boundaries and definitions of each category are not firm, the study of communication and its mediums is deep, broad, and outside of the scope of this post, but understanding your toolset through that lens may help you better select which tool is most appropriate (just because that meeting could have been an email doesn’t mean it should have been). Similarly, this perspective can be used to maximize the ease of access to any given information source. To clarify with some examples, consider the barriers in play when an individual is looking to either video conference with a colleague, or extract documented knowledge from a google doc. To reduce friction hindering them from starting a conference call you may need to focus on ensuring that they know who to contact, that they are comfortable reaching out to the domain expert, and they know when the individual with the required knowledge is available. On the opposite end of the spectrum, to reduce friction when sourcing information from an information repository like a google doc, you should focus on good naming, searchability, and on ensuring that in your information library there exists only a single source of truth for each piece of information (or at least that duplicates don’t contradict each other).

Although I’ve excluded matters of hardware entirely from this discussion so far (in short, a good mic, HD camera, and fast and hardwired internet valuable additions if available), I would like to make one specific recommendation. Given that you can’t always rely upon your coworkers to have high quality hardware of their own, I find a set of good headphones to be invaluable for making out the more muddled speakers on a call. The flip side of this of course is that headphones have the disadvantage of muffling your own voice, which many people find disconcerting and distracting while speaking. It turns out that you can have the best of both worlds—get a nice mic with aux out, and wire your headphones through that. This way the audio of your voice that the mic is picking up will be looped back to your ears sufficiently quickly that it’s almost indistinguishable from hearing yourself speak with no headphones on at all, and lets you hear people clearly without impediments to your own speech.

Keeping teams social

Perhaps the least obvious aspect of interconnectedness and accessibility of a team is the social component—the ways we reduce the friction in our teams’ communication by being friendly with each other. Reaching out to a friend, even if they’re less accessible in other ways, is almost always preferable to connecting with someone with whom your relationship has soured (or didn’t exist in the first place). Not that you should necessarily be trying to force a team to become best buddies, but it is crucial to recognize the value derived from the socialization amongst your members—specifically the ways in which it eases the processes of outreach and communication. We tend to implicitly acknowledge this with collocated groups in the form of team events, where we ostensibly build camaraderie. Certainly those are valuable, and their digital analog—the Zoom cocktail hour—can be useful as well, but there’s an enormous amount of invisible socialization that goes on in the office that we should also attempt to replicate for our distributed workers. Moments like walking to meetings together, chatting over coffee, and exchanging thoughts at a shared desk, tragically, have no obvious analogue. Instead we must engineer space for alternative activities. As I mentioned before I’m particularly partial to the start-of-meeting social which, despite initially feeling like a waste of time (at least to some) pays significant social dividends in time. That supplemented with a generous allocation of semi-social 1-1 meetings keeps me feeling connected with my organization socially, as well as professionally. And if you are the individual in charge of a team, I strongly recommend ramping up loosely structured meetings like standups and planning sessions where you can leave ample room for social margins to keep your team talking.

In a team that is tightly integrated, one of the primary goals of the teams’ organizers should be making the act of drawing upon the knowledge of a collaborator as low-friction as possible. By considering our tools, practices, and processes through that lens of accessibility, it is possible to make considerable improvements to our collective experience as distributed workers.

A Final Thought

As I mentioned before, there are many invaluable posts written by incredibly thoughtful people espousing theories of remote work, or providing lists of helpful advice for managing your new situation. The challenge then is not how to find advice, but to find advice that works for you—successful remote work is a deeply personal matter and there are few one-size-fits-all solutions. Instead, I hope that this post can provide some guidance to help you sift through your thoughts on being a remote worker and what works best for you when it comes to staying focused at home, and connected at work.

Stay safe.

Evan