I’ve been using Emacs in a remote tmux session lately and I’ve been missing lein-test-refresh notifications when my Clojure tests pass or fail. Luckily, it only took me a little bit of searching to figure out a solution for when I’m working inside of tmux.
Below is a GIF of the notifications I get as my tests run and pass or fail.
With the above notifications, I can keep my focus on my code and only switch to the tmux window with lein test-refresh running when a test fails.
This was pretty easy to setup. You can trigger a message in tmux by running tmux display-message <MESSAGE_HERE>. To configure lein-test-refresh to send notifications to tmux simply include the following in your :test-refresh section of your project.clj or profiles.clj.
In an older article of mine I extolled the virtues of having unified interfaces for interacting with your projects. I recently started working at Coinbase and the group I’m working with is mostly using makefiles as that common interface. We still have some more work to do to unify the makefile targets of the various projects but I’ve picked up one tip that makes switching between projects easier.
That tip is to have the default target of your makefile be one that prints out a helpful message. This looks like the following.
There is a lot going on there but it basically looks through your makefile targets and finds the ones that have a comment starting with ## after the target dependencies. Those targets are printed to the console along with the comment.
As an example, the makefile for my website looks similar to the below file.
123456789101112131415161718192021222324252627
.PHONY: help
help:
@grep -E '^[0-9a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
sort | \
awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
.PHONY: watch
watch: ## Watch for changes and serve preview of site with drafts
bundle exec rake clean
bundle exec rake preview
.PHONY: develop
develop: ## Serve a preview of the site without drafts and refresh changes
bundle exec rake clean
bundle exec rake develop
.PHONY: new_adventure
new_adventure: ## Start a new adventure post
bundle exec rake new_adventure
.PHONY: new_post
new_post: ## Start a new post
bundle exec rake new_post
.PHONY: deploy
deploy: ## deploy
./deploy.sh
When this file, when I run make in this websites source, I get the following output.
1234567
0 [last: 0s] 21:11:50 ~/src/jakemcc/blog (master)
$ make
deploy deploy
develop Serve a preview of the site without drafts and refresh changes
new_adventure Start a new adventure post
new_post Start a new post
watch Watch for changes and serve preview of site with drafts
This is super useful when you’re starting doing work in a new project. With this feature you can get a quick list of useful targets and a description. It allows you to quickly see what can be done in a project.
If you follow my work you probably know that I value fast feedback cycles. Most of the open-source I maintain was developed to enable faster feedback cycles. This is why lein-test-refresh and lein-autoexpect were originally created.
Leiningen supports test selectors and lein-test-refresh does as well. This lets you start-up a testing session and only run tests or namespaces with certain metadata on them. This is a super useful feature as it lets you narrow your testing scope to one (or a handful) of tests while working on solving a specific problem.
lein-test-refresh now has built-in functionality that allows you to focus your test scope without restarting the Leiningen test process. If lein-test-refresh sees a deftest or ns form marked with :test-refresh/focus true in its metadata, then it will only run tests marked with :test-refresh/focus.
I was recently having some difficulty debugging a problem in a
ClojureScript single page application. The SPA was implemented using
reagent1.
This interface stores most of its state in a global
reagent.core/atom called db. To debug the problem, I thought it
would be useful to track how the global state changed as I interacted
with the interface. How do we do that?
For the rest of this article, pretend that (require '[reagent.core
:as reagent]) has been executed.
First, let’s define db-history in the same namespace as the global
reagent/atom, db. This is where we’ll collect the changes to db.
Next, let’s write a function called aggregate-state. This function
grabs the current value in db and conjs it onto db-history. It
also limits the history to the most recent 101 states.
Now we need to invoke aggregate-state whenever db changes. We can
do this using reagent/track. reagent/track takes a function and
optional arguments and invokes that function whenever a reagent/atom
that function depends on changes.
reagent/track! is similar except it immediately invokes the function
instead of waiting for the first change. We can use it to cause
aggregate-state to get called whenever db changes.
Now history of the global state is being tracked. But we need a way to
access it. Below is what I ended up writing. When you call
ui.data.history() in Chrome’s JavaScript console, it returns an
object you can click on to explore. If you pass in strings as
arguments to history then it only selects some of the data from the
global db and history.
It only took about fifteen lines of code to gain a view of our
application’s state changes over time. This view helped me solve my
problem. Hopefully it will help you too.
This particular project is nearly four years old and has had many hands on it over the years. Working in it reminds me of how useful re-frame is on larger applications like this one.↩
A couple months ago I was looking into a problem and noticed that
there was a situation where an expensive operation could be running
simultaneously multiple times. This was wasteful.
This operation happened on a timer and could also be triggered by a power
user through the UI. A power user could accidentally (or purposefully)
mash on a UI button and cause the instance they’re interacting with
to grind to a halt1.
It was pretty easy to prevent. All I needed to introduce was an
atom and lean on compare-and-set!. compare-and-set! is a pretty
neat function (and concept found in many languages). Here is the docstring:
Atomically sets the value of atom to newval if and only if the
current value of the atom is identical to oldval. Returns true if
set happened, else false
Basically, compare-and-set! changes the value of an atom only if it
starts from a specified value and returns a boolean letting you know
if it did.
To prevent an operation from running multiple times, introduce an atom
and wrap calling the operation in a conditional using
compare-and-set!. After doing the work, be sure to reset! your
atom back to the starting value.
Below is the code.
123456789101112
(defonce running?(atomfalse))(defn- expensive-operation!'[];; do work)(defn expensive-operation(try(expensive-operation!')(finally(reset!running?false)))))
OK, not really grind to a halt, but consume unnecessary resources.↩
I typically like to reflect on my previous years reading closer to the beginning of the next year. We are just entering March, so I’ve missed doing that.
Here are links to my previous end-of-year reflections: 2013, 2014, 2015, 2016.
I’ve continued to keep track of my reading using Goodreads. My profile continues to have the full list of the books I’ve read since 2010. Here is my entire 2017 record.
2017 Goal
My goal entering 2017 was to revisit some past favorites. I started this goal without setting a number, so I’ll just have to trust how I feel about it.
In 2017, I reread Frank Herbert’s Dune and John William’s Stoner. I also read new-to-me books by the authors David Foster Wallace, Haruki Murakami, George Saunders, and Neal Stephenson. I’ve also reread a George Saunders book in the first part of 2018.
I mostly achieved 2017’s goal. If I had reread another book, I’d consider it 100% completed, but I’m going to count reading some favorite authors towards the goal.
2017 Numbers
I read a total of 49 books for a total of 17,853 pages. I also read every issue of Amazon’s Day One weekly periodical1.
The number of five-star books I read this last year was low compared to previous years.
Recommendations
I only gave out seven five-star ratings. Two of the seven were books I reread. Title links are affiliate links to Amazon and the review links are to my review on Goodreads.
Below are more details on some of the above five-star books and some shoutouts for some non-five star books. Looking back over my books, I’d recommend any four-star or higher book without hesitation but am not going to put them all here.
Lilith’s Brood by Octavia Butler
Lilith’s Brood was one of the last books I read in 2017. It is a three book series published as a single book. It is amazing. This series achieves precisely what I want in a great science fiction book. I highly recommend this book. Reading this book reminded me why I love reading.
A quote from a non-fiction essay by Octavia Butler describes why good science fiction is fantastic.
But still I’m asked, what good is science fiction to Black people? What good is any form of literature to Black people? What good is science fiction’s thinking about the present, the future, and the past? What good is its tendency to warn or to consider alternative ways of thinking and doing? What good is its examination of the possible effects of science and technology, or social organization and political direction? At its best, science fiction stimulates imagination and creativity. It gets reader and writer off the beaten track, off the narrow, narrow footpath of what “everyone” is saying, doing, thinking—whoever “everyone” happens to be this year. And what good is all this to Black people? - Octavia Butler
The Sense of Style by Steven Pinker
Yes, I read a book on writing and think this is one of the top books I read last year. I initially read a Kindle edition from my local library and then immediately bought the hardcover so I can reference it while writing.
The writing is great. The book is humorous. I’d highly recommend to anyone that writes. I should reread this.
Dune by Frank Herbert
Dune is a classic for a reason. It was still great my second time through it. If you haven’t read Dune, you are missing out.
If you read it on a Kindle, I have a custom Kindle dictionary that makes reading it more pleasurable.
Stoner by John Williams
It is still unclear to me why I like this book so much, but I do. The writing is crisp. The story is depressing.
Stories of Your Life and Others by Ted Chiang
Over the years I’ve started to enjoy reading short story collections. Every story in this collection was great. I devoured this book and then everything else I could find by Ted Chiang.
Capital in the Twenty-First Century by Thomas Piketty
This is a massive book. It probably deserved five-stars. It presents a ton of information to the reader. It is boring. It also made me think about the role of taxes in society and changed my thoughts about them.
If you’ve been putting this off, you can probably skip to the last section and still get a lot from this book.
Here is a review that does a spot on job of describing the book. Here is an Amazon link and my own review.
Bobiverse Series by Dennis Taylor
This is a fun light-hearted science fiction series. It still manages to explore some deep topics. Read the description and if it sounds interesting to you, pick it up.
Stats
Similar to last year, April and September were times when I wasn’t reading a ton.
This year physical books made a comeback. I checked out more physical books from the library this year than in the past.
I read a lot of non-fiction books this year. Only two of them were directly related to software.
1234
| | Number of books |
|-------------+-----------------|
| fiction | 30 |
| non-fiction | 19 |
2018 Goals
There are a few more books on writing that I’ve wanted to read for a while. I’m planning on reading at least one of them this year. I’m also want to read more Octavia Butler.
Unfortunately, this periodical has ended after years of publishing once a week. I’m bummed. I really enjoyed receiving a short story and poem once a week.↩
Earlier this year, I traveled to India and gave a presentation at
IN/Clojure. I talked about building serverless
ClojureScript applications that use Firebase
to persist and sync data between clients.
I was pretty pleased with how the talk went. The people who talked to
me after seemed to enjoy the presentation and were inspired to try out
some of the techniques and tools I mentioned.
Here is the talk. I hope you enjoy it. It was fun to give.
In July 2017, I found myself editing some Clojure code that looked approximately like this.
12345678910111213141516
(defn validate-required-fields[params](when-not (contains? params:source)"Missing source field"))(defn validate-invariants[params](when (>= (:lowerparams)(:higherparams))"lower field must be smaller than higher"));; route handler taken out of other routes(GET"/event-redirect/:event_type"request[](let [params(:paramsrequest)](if-let [field-error(validate-required-fieldsparams)]{:status400:bodyfield-error}(if-let [invariant-error(validate-invariantsparams)]{:status400:bodyinvariant-error}(publish-and-redirectparams)))))
This route handler validates its inputs, and if they fail validation,
then it returns an error response. I found this pretty ugly. This
small chunk of code has numerous if branches and quite a bit of
nesting. All of this makes it hard to read and hurts understanding.
While adding a new feature to it, I remembered some code I wrote with
Case back in late 2015. Back then we were
working on Lumanu and wrote a Clojure macro that we called
halt-on-error->>. This macro worked similarly to ->>, except it
allowed any step in the processing pipeline to halt execution and
trigger an error handler. We were working on a web crawler at the
time, and this macro significantly improved the readability of our
data processing pipeline. There was a lot of error handling code
throughout the web crawler, and this macro helped keep it readable.
I realized that using a similar macro would make this code easier to
follow. I recreated halt-on-error->> to allow any form to cause it
to return early. The above code could then be written like below.
12345678910111213141516
(defn validate-required-fields[params](if (contains? params:source)params(exec/halt{:status400:body"Missing source field"})))(defn validate-invariants[params](if (< (:lowerparams)(:higherparams))params(exec/halt{:status400:body"lower field must be smaller than higher"})))(GET"/event-redirect/:event_type"request[](exec/halt-on-error->>request:paramsvalidate-required-fieldsvalidate-invariantspublish-and-redirect))
Once you understand halt-on-error->>, this chunk of
code is much easier to read.
Let’s implement halt-on-error->>.
Implementing halt-on-error->>
Here are some tests for that specify how halt-on-error->> should work.
So what is this macro doing? First, it uses gensym to get a symbol
with a unique name and stores this in g. It then defines a helper
function called pstep for use in the code generation part of the
macro.
This macro generates a let block that repeatedly executes a form and
assigns the return value back to g. g is then checked to confirm
execution should continue before it is threaded into the next form. If
g is ever an instance of a Stopper, execution halts and the value
wrapped in the Stopper is returned.
Looking at an expanded version of a macro can be easier to understand
than a written explanation. Below is a macroexpanded version of one of
the tests.
12345678910111213141516
;; What is being expanded(macroexpand-1 '(exec/halt-on-error->>(success-fn"first""")(produce-error)(success-fn"second")));; The expansion(let [G__15365(success-fn"first""")G__15365(if (instance? halt.execution.StopperG__15365)G__15365(->>G__15365(produce-error)))G__15365(if (instance? halt.execution.StopperG__15365)G__15365(->>G__15365(success-fn"second")))](if (instance? halt.execution.StopperG__15365)(.xG__15365)G__15365))
Looking at that expansion, you can see how we are using a let block
to repeatedly assign to the same symbol and we check that return value
before executing the next stop.
This isn’t a new pattern. There are
libraries that implement
similar ideas. At IN/Clojure 2018, Varun Sharma gave a
talk
about how this cleaned up their code. You can even get bogged down and
throw around words like monad when talking about it.
I’d encourage you to look at your code and see if you have areas where
error handling code is detracting from the readability. This might be
an area where this, or something similar to it, would help.
I recently needed to optimize the speed of some Clojure code. After investigating, I identified that a huge number of exceptions were being thrown and handling these was slowing down the process.
The code throwing the exceptions was parsing strings into Joda-Time DateTime objects using the clj-time library.
The code was calling clj-time.coerce/from-string which calls clj-time.format/parse. format/parse iterates through up to approximately 50 formatters in an attempt to parse whatever string you pass it. If one of these formatters doesn’t parse the string, it throws an exception which format/parse catches and ignores before attempting the next formatter.
This was pretty wasteful. This was especially wasteful in the code I was working in since it only needed to handle two different date formats.
Luckily, Joda-Time has a way to build a formatter that handles multiple formats and clj-time provides access to it. Below is code that creates a formatter that handles two different formats.
Looking back at that code, it seems pretty straightforward. I’ll admit that it took me and my pair a while to figure out how to do this using clj-time. I ended up looking at Joda-Time’s documentation and implemented this using Java interop before I cracked how to use clj-time.format/formatter to do the same thing.
See all of my remote/working-from-home articles here.
Whether it is working as the one remote employee at a traditional company or being one of many at a distributed company, remote work is becoming an option for many of us.
The number of employees that work remotely is growing1. Technology improvements, pervasive Internet, and mindset changes are some of the drivers for this change.
The remainder of this article highlights some observations from my last few years of working for distributed companies. I’ve also interviewed and corresponded with many other remote and formerly remote workers. Their contributions, along with books and articles on remote work, have influenced my thinking about what it means to have a successful distributed company. I’ve been working remotely since October 2013 in roles that have ranged from being a team lead to software developer to CTO. Each company I’ve worked for was fully distributed. There were no offices.
The types of distributed companies I’ve worked with have not been asynchronous. They have had core working hours centered around one of the middle time zones in the continental United States. You could work from anywhere, but you needed to be willing to work while others were working. I consider this synchronous remote work.
Much of the following also applies to individuals working remotely for a not-entirely-distributed company or team. Being the only remote individual in a non-remote team comes with its own set of challenges that I’m not going to attempt to present. If you are part of a team where some members work remotely, my recommendation is that you should treat that team as a remote team. If you don’t, the remote worker will have a harder time keeping up with the rest of the team.
Benefits
If you ask someone that has never worked remotely before for the benefits of working remotely, they would probably be able to guess at some of the most obvious benefits. The top two responses I’ve received to this question are having no commute and more flexibility in your schedule. These two advantages are huge. There are other, less obvious advantages as well.
No commute
This is the benefit that most workers, remote and non-remote, identify when asked about benefits of remote work. This benefit stands out because it is huge and obvious. In the United States, the average one-way commute is 25 minutes long. The average worker spends nearly one hour going to and from their work.
If you are going to work five days a week, then you’re spending over four hours commuting. That is half of a full workday riding a bicycle, car, train, or bus. In the best case scenario, you are using that time to read, listen to a podcast, or trying to think deeply about a problem. In reality, you’re trying to do one of those activities, but you are continuously distracted by the world around you. You have to worry about avoiding accidents, driving safely, or another distracting concern.
Commuting has been shown to have negative effects on the commuters2. Being able to work remotely lets you avoid those problems.
Flexibility in schedule
This is another benefit that most people can immediately identify. Remote works gives you more power over your schedule. Even if you’re part of a synchronous distributed team, you gain flexibility. All of a sudden your breaks become time you can use to enrich your non-work life.
Picking up or dropping off your children at daycare or school becomes easier. Taking your dog for a midday walk becomes possible. Since you aren’t commuting, you have more time to make breakfast for you and your family. You can run errands or go to your favorite neighborhood lunch spot during the day. These errands and restaurant trips are quicker since you’re effectively doing them at off hours as most of your neighbors are working at their office.
More time with family
If you’re working at home, then it becomes easy to see your family more. You can say hi to your kids when they get home from school. You have more time in the evening to spend with your baby before bedtime.
Customize your workspace
You get to choose where you work. For many, this will be in a home office. This is your space. You get to make it your own.
Do you like to work in a cave? Paint the walls a dark color, block out the windows and enjoy your cave-like experience. Do you prefer sunlight and plants? Work near a window and add houseplants to your space. Do you want an awesome sit-stand desk and chair? Buy them.
One of my former colleagues likes to walk on a treadmill while standing or, if sitting, he enjoyed having pedals under his desk. These are customizations he would have a hard time getting at most offices.
Eat the food you want to eat
Many of us have preferred diet (or a diet we’re forced to follow). When you work from home, it is easier to eat food you know you should eat.
When you work from an office, you have a few food options. You can bring your food, go out to eat, or (if your employer offers it) eat food provided by your company. If you follow a restrictive diet, all of these options are more hassle than making your lunch at home every day.
Feel like eating food someone else has prepared? You can still do that while working from home.
Fewer interruptions
As a remote worker, you can choose your working location. This lets you select a spot with fewer distractions. You can pick an ideal location that helps you achieve a state of flow.
Minimizing interruptions is one of the keys to accomplishing challenging tasks. After an interruption, it takes up to a half an hour to get back to your original task3.
Off-hours support
This is a benefit I have not seen mentioned many other places. Off-hours support becomes much easier if you are working remotely. The actions you would take for an urgent alert at 1 AM are the same actions you would take at 1 PM.
When you get that 1 AM page you don’t have to struggle to remember how you check production while at home; this is an activity you do on a regular basis. You know what you need to do. You don’t have to remember how to VPN into your company’s network; you do that every day.
No one likes getting woken up by a support call. At least this way you get to use your normal tools for solving problems.
Recruiting
Since you aren’t limited to your locale, you can recruit from a much broader region. This means you can find the top talent for your company. This is huge.
Back in late 2013, it was quite challenging to find experienced Clojure programmers. Because Outpace is a distributed company, we were able to hire experts from across the entire United States. We would not have been able to recruit nearly as well if we were limited to a single location.
Employee retention
If your company supports remote work, then you remove an entire reason for an employee leaving. Sometimes, a person needs to move. Working for a company that supports remote work allows them to move and not leave the company.
Reduced office costs
Having a distributed workforce can reduce office costs drastically. In a fully distributed company, it could reduce the cost to zero. Realistically, I’d expect the company I work for to provide computer hardware so there are still some costs4. Unless the company pays for Internet and phone, the recurring costs are minimal.
Downsides
While there are many benefits, there are also downsides to working remotely. When I talk to non-remote workers about working remotely, I typically hear “I don’t know how you do it, I’d be so distracted.” This statement touches on one of the downsides of remote work, but it isn’t largest one. Below are some downsides that I and others have observed.
Loneliness and isolation
Nearly everyone I’ve talked to, including myself, puts this as the top downside.
Most of us are social creatures. You do not get the same type of social interaction with your coworkers when you are working remotely. Instead of bumping into a wide range of people in the office, you interact with a smaller group through video chats, phone calls, chat rooms, and email. Depending on what you are doing, you might not even get that interaction.
This is very unfamiliar to most of us. We’re used to being in physical proximity to other humans. We’re used to having small talk and grabbing coffee or lunch with other people.
You can combat these feelings by setting up communication with other employees at your company. Have some dedicated chat rooms for non-work discussions. Have a daily, short video meeting that is a status check within the team so that everyone gets to see another person’s face at least once a day. If you work in a city that has other remote workers from your company then meet up occasionally for dinner, lunch, or happy hour.
If you are having troubles with loneliness and isolation, try to find an area where you can work surrounded by other people. Two options are co-working spaces and coffee shops. Alternatively, try to have social activities you regularly do with non-coworkers in your area. Having strong connections with non-coworkers can help combat loneliness.
If I stay inside for more than a couple days, I get grumpy. I didn’t realize this when I worked in an office. Noticing this has benefited my rock climbing, as I’ve made that my main non-work social activity. Even if I merely go bouldering by myself, being around other humans helps. If you’re working remotely and feeling grumpy, try to find an activity you can regularly do and see if doing that helps.
Distractions
This is the downside that non-remote workers most often identify. People assume that television and other distractions in your home are irresistible and will cause you not to get work done. When you are working 100% remotely, you don’t have the same distractions you have when you are only occasionally working remotely. You can’t do laundry every day. You only have so much TV you can watch.
Personally, I don’t have a problem with distractions when working at home. I know others that do. They mostly have when they first started working from home. When they first started working at home, they found themselves doing too much around the house. As a result, they worked late hours or felt like they weren’t getting enough work done. Once you recognize the problem, it is possible to train yourself not to get distracted.
Roommates, kids, and family are another (sometimes welcome) distraction. You can combat interruptions from others by setting boundaries. Many of my coworkers have a rule that when their office door is closed, they are unavailable. I’ll claim that coworkers interrupting you in an office are more distracting as the much rarer interruption from someone within your home.
Employees that work remotely are typically choosing to work remotely. Once they get used to working remotely, distractions stop being a problem. They know they need to produce quality work and will take steps to make sure they do.
Working too much
When you first start working from home, you suddenly find yourself living in the same space that you work. This lack of change in location and commute makes it easy to keep working. You get invested in a problem and all of a sudden it is past the time when you should have stopped working.
Even if you manage to stop working on time, it is easy to slip back into work mode. The computer setup I like to use in the evening is in the same location as my work setup. This makes it easy for me to take one more peek at our monitoring dashboards or check my work email.
You do not want to overwork and you do not want your teammates to overwork. In the short-term, overwork can be beneficial. Long-term it leads to burnout and poor outcomes.
Fewer interactions
This is a negative and positive. When you are working remotely, you have fewer random interactions with coworkers. You most likely interact with your team plus the same handful of people outside of your team regularly but you rarely interact with others.
In an office, there is a chance you’ll run into people outside your usual circle of communication. You might eat lunch with a broader variety of people. You may bump into others while getting a coffee or a snack.
You can help increase interactions on a distributed team by having some chat rooms that encourage random discussions. Another option is to have a regular and optional meeting scheduled where people can give an informal presentation on something that interests them.
Tools
You will need to select tools that work for distributed teams. Most computer or web-based tools can work in a distributed setting. Any physical tools (such as pen and paper) will not work.
A prime example of this is the classic card wall for tracking work. A physical wall with actual cards will not work as soon as there is a single remote worker on a team. Instead of a physical wall, you’ll need to using something like Trello.
It is less important to get stuck on a particular tool recommendation and more essential to pay attention to the categories of tools. Categories of tools tend to be more stable than a specific recommendation.
Text chat
You’ll want a chat application. Slack and Stride are just two of the many available services.
Video conference
Video conferencing is a technology that you should embrace. It is much better than talking to either an individual or a group on the phone. Being able to read body language makes communication far better. Personally, I’ve used Google Hangouts and Zoom for hundreds of hours each and prefer Zoom. appear.in is another option that doesn’t require installing anything. There are many options in this space and more keep appearing. It is even built into Slack.
Phone conferences
I’d try to get rid of phone conferences in preference to video conferences. Video chat has many benefits over conference calls. I actually can’t recommend any phone conferencing tools, but I will mention that Zoom supports people dialing into a video conference.
Screen sharing
You’ll want to have a way to show another person or group what is on your screen. It is even better if someone else can take control of your machine or use their cursor to point towards something on your screen.
Most of my experience with this is using the feature built-in to Zoom. Pretty much every video conference tool I’ve used (appear.in, Google Hangouts, etc.) has screen sharing built-in.
Real-time collaboration on a document
Being able to collectively edit a document with a group is pretty amazing. Etherpad and Google Docs are two options. Most of my experience is with Google Docs.
When a document supports real-time collaboration, you can do amazing things. You can use it to capture ideas from a remote group. An extreme version of this can be viewed by opening this page and searching for “Google doc.”
You can use a shared document to facilitate a remote meeting (this goes incredibly well once you get the practice of it). Having a document that everyone in a meeting can edit is so much better than a whiteboard that only one or two people can simultaneously use.
Whiteboards
Whiteboards are an example of a tool that is always brought up, even by remote workers, as something that distributed teams miss. There are alternatives.
Whiteboards are a very convenient tool when meeting in-person, but there are other ways of collaborating when working remotely. Shared documents and screen sharing go a long way towards enabling collaboration. Tools that work well for remote collaboration often have another benefit over whiteboards; they are easier to persist and reference later.
One whiteboard alternative is Zoom’s built-in whiteboard. It works fairly well. Another is to use Google Drawings. Precursor is a design focused collaborative tool that can also work.
Even after four years, I occasionally find myself missing a whiteboard or shared piece of paper. Drawing with a mouse isn’t ideal. I know some developers that use an iPad or a Wacom tablet to help them quickly sketch diagrams for their team.
Communication
Communication is inherently different on a distributed team. You cannot just walk across an office to interrupt someone and ask them a question. Communication happens mostly through text. You need to be skilled at written communication.
You lose context with written communication when compared to vocal or in-person communication. You no longer have body language or tone of voice to help you interpret what someone means. Lack of tone is huge. This is one reason that text communication is interpreted as more emotionally negative or neutral than intended5. If you’re reading text communication, try to read it with a positive tone.
It can also be useful to have rules around the expectations of different forms of communication. How quickly do you need to respond to an email? How quick should a response be to a chat room message? When should you pick up the phone and call someone?
Chat rooms
Chat room applications (IRC, Slack, Stride, Flowdock, etc.) are pretty great. They provide a medium of communication that has a lower barrier to entry than email. Chat tools have a place in the distributed teams tool chest.
The chat room becomes even more central to work once you start including useful bots in the room. These bots can perform many functions. You can look in the Slack App Directory to see some of the bots that people are producing.
If you start adding bots and other automated messages to your chat application, you might want to think about setting up a separate channel. Some messages are not worthy of being interjected into your team’s main chat. They can be distracting and hurt the flow of conversation. These messages tend to be ones that are informative, but not critical. For my teams, these messages include things like git commits and Trello card updates. It is great to see these in a single spot but annoying when they interrupt a conversation.
Chat rooms can also be a big time sink. They are a source of concentration interrupting notifications. The feeling of missing out on conversations can drive people to join a large number of channels. This piles on the potential for distraction.
Chat rooms also provide a feeling of immediacy that isn’t actually there. You don’t know if key people have seen your message or have had time to respond.
Despite having search functionality, I’ve found it hard to find previous conversations in chat applications. If something important appears in chat, I’d recommend extracting it from the chat application and recording it somewhere else.
I’d also recommend turning off notifications for all but most definite “someone is trying to reach me” triggers. Encourage members of your chat to use entire channel notifications sparingly and only for messages that need everyone’s attention. There are not many messages that immediately require everyone’s attention.
It can be a challenge to follow chat conversations, especially if they span a larger unit of time. Don’t be afraid to move a conversation to email or another medium that is better suited for longer and more complex discussions.
Many chat applications offer the ability to have private rooms or to send direct messages to a user. Don’t be afraid of using these private channels, but if your communication can be public, it should be public. It can be challenging to ask a question and admit you don’t know something but seeing that dialogue might help others. Similarly, having discussions about a feature, bug, or task can help spread knowledge.
Email
Despite all of the efforts to replace email; email is still useful. It is the most common form of communication between companies, it is pervasive, and it usually comes with good search capabilities.
A good email thread can keep a topic contained in a form that is possible to follow. Unlike a chat room, there (usually) aren’t off-topic interjections from uninvolved parties.
Phone
You shouldn’t be afraid of calling someone. Just recognize that this is an interruption. Your company should have a directory of telephone numbers that is accessible to everyone.
One downside of any voice conversation is that it is not automatically persisted. It can be worth following up a phone call with an email summarizing the discussion and the next steps.
Picking the right communication medium
When you are working on a distributed team, you can no longer walk over to someone’s desk and interrupt them. This is great. Not every question deserves an immediate answer.
Agree with your team when to use different forms of communication. Set expectations with regards to response times and urgency for different mediums. Maybe direct chat messages are expected to be responded to in under 10 minutes. Perhaps emails are OK having a delay of a few hours. This is something your group will need to decide.
Practices
These are some practices I’ve seen work well with distributed teams. Many of them are slight variations on what you might have experienced on a co-located team.
Stand-ups
Most of the teams I’ve been part of, whether distributed or co-located, have had a daily stand-up meeting. The intention of this meeting was to provide a short, scheduled time for communicating any roadblocks to progress, interesting information, status updates, and desire for help.
For a distributed stand-up, the team joins a video conference and we gather around a shared Google Doc that has prompts similar to the snippet below.
These prompts provide a starting point for team members to add additional text. Our stand-ups were at the beginning of the day, so frequently team members would add text to the document at the end of the prior day. Filling in the document at the end of the day instead of right before the stand-up was useful as memories and thoughts were often fresher without having to remember them the following morning.
After being filled in, the document would look like below.
1234567891011121314
Day: 2017-07-11
What's interesting?
- New deploy lowered response time by 20% [Jake]
- Discovered bug in date-time library around checking if date is within interval [Sue]
- Greg joined the team!
- Adding blocker functionality going to take longer than expected [Donald]
Want help?
- Having difficulties running batch process locally. [Tom]
- I'm having a hard time understanding propensity calculation [Mike]
Meetings:
- API overview with client @ 2 PM Central [Jake/Jeremy]
We would gather around the Google Doc and everyone would take a couple of minutes to read silently. If anyone felt like something was worth talking about they would bold the text and then we’d work from top to bottom and have a quick discussion. For our Want help? section we’d solicit volunteers and move on. The Meetings section was primarily there to provide visibility as to when certain members might not be available. After we worked through the Want help? section we’d pop over to Trello and review the work in progress and make sure everyone had an idea of what they would be doing that day.
The nice thing about doing a stand-up around a shared Google Doc is that you can put in richer media than just text. Screenshots of monitoring graphs were a regular addition to the What's interesting? section.
Every day a new section was added to the top of the Google Doc and the previous day was pushed lower on the page. Having this written history of stand-ups was useful as it allowed us to notice patterns through a persisted medium instead of relying on our memory. It also let someone who was on vacation come back and have an idea of what had happened while they were gone. Below is what the document would look like on the next day (comments removed to keep the example shorter).
Above is an example from one of the teams I led. Another team used the following prompts.
1234567
1. Accomplished Yesterday
2. Requires Attention/Roadblocks
3. Scope Creep Alerts
4. Would like to Do Today
The important thing is to find something that works for your team. Different teams are going to prefer different formats.
Another interesting benefit of using a Google Doc to drive your stand-up is that it can be visible to other teams. You can even combine teams into a single document. Below is an example with two teams in a single document.
I’ve seen this work successfully with five related teams in a single document. News and information that affects everyone is added in the Everyone section. Team specific information is put in the team sections. Each team still has their individual stand-up where they only look at their section. But since their section is part of the larger document, they get a taste of what is going on in the other related teams. This helps replace the random hallway chatter you get in a shared office and gives everyone a slightly broader picture.
This worked shockingly well. I’ve had colleagues reach out, some years after leaving, to ask for the template we used for this multi-team stand-up.
Stand-downs
Stand-downs are a meeting that provides time to informally chat with a group. I’ve seen them used as an optional end-of-day water cooler activity for a group to talk about whatever. These chats often happen, but are unscheduled, in an office.
These meetings should be an optional, short meeting scheduled near the end of the day. This gives team members a good excuse (socializing with their coworkers) to stop working (which helps with the problem of overwork). No one should feel pressure to be at these meetings.
The conversation may or may not be work-related. Maybe you discuss a language feature someone learned. You might talk about a book you started reading. It doesn’t matter what is discussed; these meetings can help a team get closer and promote more social interaction.
I’ve also worked with teams that play games, such as Jackbox Party Packs, through video conferences.
Remote Pair Programming
Pair programming is a technique that people often employ when working in-person. It works even better when remote and helps solve some of the difficulties of working remotely.
Remote pair programming helps fight the feeling of loneliness and isolation that remote workers feel. Remote pairing forces intense interaction between two people. It also helps keep the two people focused on work. It is easy for a single person to get distracted by browsing Hacker News but much harder for both people to get sucked into it.
The ideal in-person pair programming setup is when you take a single computer and hook up two large monitors, two keyboards, and two mice and then mirror the monitors. This lets both programmers use their personal keyboard and stare straight ahead at their monitor.
Remote pair programming is an even better setup. One developer, the host, somehow shares their environment with the other developer. This can be done through screen sharing using Zoom, Slack, VNC, tmate, or some other way. The important part is that both developers can see the code and, if necessary, someway of viewing a UI component. They should both be able to edit the code.
Like the ideal local pair programming environment, each developer uses their personal keyboard, mouse, and monitor. Unlike the local pair programming environment, they each also have their own computer. This lets one developer look up documentation on their computer while the host developer continues to write code. It also allows the non-host developer to shield the host from distractions like answering questions in the chat room or responding to emails.
When remote programming it is easier for the non-host developer to stop paying attention. It is easier to be rude and not pay attention to your pair when you are not sitting next to them. If you notice your pair has zoned out, nicely call them out on it or ask them a question to get them to re-engage.
One-on-ones
One-on-ones are a useful practice in both a co-located and distributed team. For those who aren’t familiar with one-on-ones, they are meetings between you and your manager (flip that if you are the manager). They should be scheduled regularly and be a time where you discuss higher-level topics than the daily work. They are extremely useful for helping you develop professionally and helping a team run smoothly. If you currently have one-on-ones and you aren’t finding them useful, I’d recommend reading some articles with tips for making them useful. Here are a couplearticles that give some pretty good advice. As both a team lead and a team member I’ve found one-on-ones extremely useful. I thought they were even more useful when on a distributed team.
With a distributed team you lose out on a lot of the body language you can pick up on when in person. It is harder to tell when someone is frustrated or when a pair is not working well together. Burnout is harder to notice. One-on-ones provide a time for that information to come out.
Meet in person
You should have your distributed team or company meet in person. This shouldn’t happen too regularly; I think this ideally happens two to four times a year. Even if you see someone every day on video, there is still some magic that happens when you meet in person6.
You can use this time to do the typical day-to-day work, but I think it is more productive to try other activities. The most successful in-person meetups I’ve been part of consisted mostly of group discussions. This can take the form of a mini-conference or Open Space. Another option is to brainstorm some potentially wild ideas and try implementing them to see how far you can get.
Use this time to have some meals and drinks with your coworkers. Play some board games and talk about things other than work. Sing some karaoke. Get to know your coworkers as more than someone inside your computer. Doing so can help with communication and understanding personalities.
End
It is an exciting time to be a remote worker. New tools are emerging that try to make remote work easier. New techniques are being discovered. Old techniques are being adapted.
I hope you’ve found this article useful. If you are a remote worker, maybe you’ve picked up some ideas to bring into your remote work. If you work in an office, perhaps you’ve found some useful arguments for moving towards remote work.
There is much more I could write about remote work and distributed teams. Some of these sections deserve their own posts and extended examples. You can view the remote category of my site to view other articles I’ve already written.
If you’ve enjoyed this article, consider sharing (tweeting) it to your followers.
