Discussions in Async | Author: | Created on: Dec 25th 2018 | Last edited on: 3 months ago


In our previous article, we talked about how different professions require a different amount of asynchronicity for communication. For example, scientists and software engineers prefer mostly asynchronous communication, whereas sales people and stock traders prefer synchronous. To learn why, check out our article: Async is out of beta launch .

In our "Async is out of beta" article, we also mentioned how we, as a small team of software engineers, think about Issues. In particular, we talked about how we track the progress of individual GitHub Issues using Basecamp's Hills launch .

When we work on a software project, we use Issues for relatively big tasks: a feature that affects our app on many levels, a bug that is multi-layered, and refactors such as redefining models and running database migrations. Though we don't have a precise set of rules to qualify a task as "big enough" - surprisingly, 95% of the time we agree on whether a particular task deserves a new Issue.

You and your team may choose to create a new Issue for small tasks as well. However, for us, tracking progress via Hills for small tasks is counter-productive. If the task is small, changing the Hill's state takes more time than completing the task.

Instead, we use Discussions to work on smaller tasks, such as simple features (changing divs, color, or adding a simple button), small bugs (fixing a broken link), asking questions, and discussing an existing or upcoming feature.

We typically create multiple Discussions to work on a single Issue. For example, an Issue that modifies a model could have these Discussions:

  • updating model schema
  • updating static CRUD methods on the server
  • updating internal API CRUD methods on the client
  • migrating data for existing documents on the database

There also could be multiple Discussions that focus on testing/reporting/clarifying/iterating and etc.

In this article, we describe how we use Discussions in Async and why we built Discussions in a certain way. When possible, I will provide real-life examples.

We built Async's Discussion feature to have the following properties:

  • Asynchronous
  • Focused
  • Long-form
  • Intuitive
  • Transient

Asynchronous

Professions that require deep focus (scientists, engineers) benefit from using more asynchronous communication. Asynchronous communication means communicating parties don't require an immediate response from each other. A good example is email. As we mention in Async is out of beta launch , for professions needing asynchronous communication, work typically happens in cycles: Discussion -> Execution -> Discussion -> Execution -> ... Once work is discussed and agreed upon, people begin executing and interruption is discouraged.

With this in mind, we made Discussions and Posts specifically for asynchronous communication:

  • Discussions consist of Posts
  • Posts are displayed as a single thread
  • New Posts are added to a Discussion asynchronously
  • There is no way to see if other participants of the Discussion are online
  • There is no way to see if other participants read your Post
  • The default notification for a new Post is a basic visual clue (no sound, no popup):
    Async

As you can see from the screenshot above, the notification is a dot next to the new Post, plus text on the browser tab.

When executing, interruption is discouraged but not eliminated. If, say, a research lab caught on fire OR a new software version is deployed with a critical bug, then scientists or software engineers must be interrupted and communicate in real time.

To account for that - if you deem a certain Discussion to be more urgent than others, you can change the default notification to be browser + email:

Async

If selected, participants of the Discussion will receive an email for each new Post. This email will contain the content of the new Post and a hyperlink to the Discussion.

Focused

We designed Discussions to be asynchronous so they are non-interrupting. As we described above, a Discussion is structured as a single asynchronous thread. Unlike Slack's channel that encourages participants to quickly chip in, a Discussion encourages participants to take time to think and stay on topic.

Besides asynchronicity, there are a few other design elements that contribute to making Discussions focused.

  • A Discussion has participants. Only the selected participants will see a Discussion and be notified about new Posts:

    Async
    Async
  • In addition to participants, we use tags. Tags allow us to categorize Discussions by common topic and better organize our list of Discussions. Currently, our team has the following tags for Discussions: Question, Feature, Bug/Error. The tags names are self-explanatory.

    Async
  • As mentioned in this article and our previous article launch , we use Issues for big tasks like multi-layered features or bugs. Typically, we end up creating multiple Discussions to discuss and close a single Issue. We decided that in addition to organizing by tags, we should be able to add an Issue to a Discussion. Once you add an Issue to a Discussion, a hyperlinked name to the Discussion will appear under the first Comment of the Issue.

    Async
    Async
    This feature allows the team member who works on a particular issue to track down all relevant Discussions more quickly:
    Async
  • Finally, we encourage our team members to give a short but informative title to any new Discussion. Typically no more than 3 words. Most of the time, it is just one word. On the list of Discussions, the title of each Discussion is truncated to help create an informative and short name.

Long-form

Asynchronicity and focus allow us to think longer and deeper before replying. We switched from Slack to Async about 3 years ago, and we noticed (among other improvements) that our replies became more thoughtful. We needed fewer replies to resolve an issue, and we spent less time switching back-and-forth on ideas. Async basically encouraged us to think and write in longer form.

Async

We take more time to write a single reply, but our overall time to resolve a Discussion or close an Issue is much shorter.

In some situations, a reply needs to be saved before it's ready to be shared with the participants of a Discussion. To address this, we created a feature to save a draft Post. You can save your Post's content, and this draft is invisible to the Discussion participants.

Async

Async

Intuitive

We aimed to make Async and its Discussion as intuitive to use as possible. As a result, more than half of the user experience was inspired by email clients and GitHub. For example, we highlight unread Posts and Discussions that contain unread Posts. In addition to tag-based organization, you can prioritize a Discussion to the top of your list by starring it.

Async

Discussion Posts support markdown, and Async's markdown is similar to GitHub's.

Async

Async

As we mentioned earlier, you can choose to notify a Discussion's participants by email. If a participant receives an email notification about a Post, this participant can create a new Post at Async by simply replying to the email. This new Post will be auto-created at Async with the content of the email reply. This is a handy feature for users without access to Async, perhaps someone working from their phone and or on-the-go.

Though asynchronicity is at the core of Async's Discussions, a lot of updates within Async happen in real time. For example, newly created Posts appear instantly on a Discussion thread. We are a remote team, and we live in drastically different time zones. Even so, we have a few hours of overlap. When we overlap, we appreciate seeing new Posts appear in real time, without needing to manually reload the browser tab.

So far, we discussed "intuitive" features that are inspired by email clients and GitHub. Here's an example of an "intuitive" feature that we created ourselves. When writing a Post, you can use keyboard shortcuts to quickly reference any Discussion, Knowledge document, Todo, Issue, or Commit. You can load a list of any item by typing:

  • @ to trigger list of repo members,
  • #d - list of Discussions,
  • #k - list of Knowledge docs,
  • #t - list of Todos,
  • #i - list of Issues,
  • #p - list of Pull Requests,
  • #branch#c - list of Commits.

List of repo members:

Async

List of discussions:

Async

List of issues:

Async

This saves a lot of time, because there is no need to manually search and reference any of the above items.

Transient

When we thought about whether Discussions should be deletable or archivable - we realized that the majority of our Discussions do not deserve archiving due to the transient nature of their content. Most Discussions solve a problem, and the content of the Discussion has no valuable knowledge to preserve. Such Discussions do not need to exist after the problem is resolved. In addition, we found that searching within thousands of archived Discussions is frustrating. These considerations made us realize that Discussions are meant to be deleted once resolved.

Async

Async
Async

We introduced a simple feature that allows a Discussion's participants, except the author, tell the author that the problem is resolved and the Discussion can be deleted. Making Discussions deletable results in many advantages for user experience:

  • the list of existing Discussions is short and manageable
  • searching within existing Discussions is fast and not overwhelming
  • loading data, such as a list of Discussions, is fast

On rare occasions, a Discussion results in some valuable knowledge that should be preserved and shared. When this happens, we take this knowledge and save it as a Knowledge doc. We will describe Knowledge docs in one of our upcoming articles.

When you want to save content from a Discussion, copying markdown from any Post is straightforward:

Async

This article describes the key features of Discussions in Async. To our small team of software engineers, asynchronous Discussions gave a big boost to our creativity and productivity. Building software requires deep and focused Discussions with periods of uninterrupted work, and that's exactly how we designed Discussions in Async to be.

Though we can't speak for big teams, we learned that big companies such as Wordpress, GitHub, Zapier, and even Stripe have their own in-house built solutions for asynchronous communication.