Async work: what to write down and when to call

Write down what someone else needs to find later or understand without you: decisions with the reason behind them, questions with enough context, and where your work stands. Get on a call when something goes back and forth without progress, or when you need to work something out together. After that call, write the outcome down anyway.

I work as a developer from Serbia in client teams. Serbia shares a time zone with the Netherlands and most of Western Europe, so we overlap the whole working day. For me, async work is a way to get focused time and to record knowledge that would otherwise stay in someone's head.

What always goes in writing

I always write a few things down, even when they were discussed on a call:

• Decisions, with the reason. In six months nobody remembers why the choice was made, but the ticket or the commit still does.
• Assumptions. If I have to continue without an answer, I write down what I am assuming, so someone can correct me before it reaches production.
• How to run or test something. That belongs in the README or the pull request description, not in a chat message.
• What I deliberately did not do. Then a reviewer does not think I forgot it.

A question that can be answered in one go

The classic "got a minute?" costs time twice: the other person has to reply, and then you still have to ask your question. So write out the full question straight away. Give the context, say what you already tried, ask the specific question and say what you will do if no answer comes.

For example:

The ticket for the new discount rule says the discount also applies to existing subscriptions. Should I recalculate running subscriptions retroactively, or only from the next invoice? I am going with the next invoice for now and will note that in the PR. Tell me if it should be different.

Someone can answer that with one word between two meetings, and if the answer takes a while, the work does not stop.

When a call works better

Writing works badly when you need to work something out together. A design choice with three options and four opinions does not get settled in a thread. I also call when a discussion is still going nowhere after three messages back and forth, because ten minutes on a call is cheaper than another hour of typing.

Feedback that could land wrong is also better on a call. A critical remark comes across harder in writing than intended, especially in a second language. Our working language is English, and in a mixed team that is often not everyone's first language.

After the call I write two or three lines in the ticket or thread: what we decided and who does what. Otherwise the rest of the team does not know what was agreed.

Pull requests are documentation too

A good PR description saves a call with the reviewer. I put in what the change does, why, how to test it and what I deliberately left out. For a UI change I add a screenshot or a short recording, and the link to the ticket goes at the top.

That sounds like a lot for a small PR, but it is usually a few lines. The reviewer then does not have to piece together the ticket, the chat and the code to understand what is going on. The review itself is the subject of code review in a remote team.

Making the state of your work visible

Remotely, nobody sees that you are stuck. If the work is not done at the end of the day, add a short update to the ticket: where it stands, what the next step is and whether you are waiting on something. That takes a minute, and whoever picks up the ticket tomorrow, or is waiting on it, does not have to ask.

The board has to be right. A ticket that says "in progress" while you are working on something else gives the team the wrong picture. The stand-up then turns into a round of chasing people instead of a short check on what is stuck.

One place for each kind of information

Nobody finds information that is scattered across tools. Keep one place for each kind:

• decisions and context in the ticket, or in a short note in the repository if it affects the architecture
• explanations of how something works in the README or the docs in the repository
• discussions in a thread in the team channel, not in direct messages

Direct messages are convenient, but what is said in them is known to exactly two people. When I ask something in a DM that would help others too, I post the answer in the channel or the ticket afterwards.

What the client can do

Async only works if questions get answered. Agree how fast that happens, for example within half a working day. Say when you are unavailable for a day, and who answers instead. Also accept that a developer moves on with a written-down assumption instead of waiting. That is faster, and if the assumption is wrong, you will see it in the PR.

How we set up the rest of the collaboration is described under how we work.