Knowledge docs in Async | Author: | Created on: Sep 3rd 2019 | Last edited on: 16 days ago


In the previous articles of this category, I described how Issues launch and Discussions launch work in Async. In this article, I'll discuss another important part of asynchronous communication: Knowledge.

As you may have learned from reading our previous articles or from using Async - we recommend using Issues for relatively large, multi-layered tasks and using Discussions for smaller, single-layer tasks. For example, refactoring a feature could be an Issue, and you could track progress via Issue Hills launch . This refactoring Issue would probably have multiple Discussions associated with it. One of those Discussions could be about a bug found during testing. Another Discussion could be feedback from a customer. Issues are meant to be closed when completed, and Discussions are meant to be deleted when resolved.

So an obvious question is where do we keep our shared Knowledge that we generate as a team?

We save any information that we deem to be important to Knowledge. For example, a script that tests a lambda function locally or instructions on deploying our API server to AWS are types of information that are generated during Discussion but are preserved and shared using Knowledge. As a rule, we outline a detailed description of a task and high-level implementation of it inside an Issue. We then break a large task from the Issue into smaller pieces and discuss these pieces one by one using transient Discussions. Saving our team's knowledge into an Issue or Discussion is not practical - thus, we created Knowledge.

Differences from Discussions

  • Unlike Discussions, Knowledge has no Posts. It is a single document that is meant to be shared and exist for a long time.

  • Inside a Discussion, every participant creates and edits their own Post. However, in Knowledge, all participants can edit Knowledge created by one of the repo members. Everyone who is a participant of Knowledge is able to edit the document. Only the author can delete it.

  • When a user adds or edits a Post inside a Discussion, Async creates a new notification. Async displays a new notification on the Post, Discussion and browser tab. However, there is only one Knowledge document that team collaborates on and edits fairly frequently. Thus we decided not to create a new notification when a user edits a Knowledge. Although there is no notification for editing Knowledge, all participants are notified when a new Knowledge is created. We did it this way to minimize distraction. Knowledge is not designed to support an urgent discussion but to collect and accumulate team's knowledge.

Similarities to Discussions

  • Similar to Discussions, Knowledge has the same content management: file upload, markdown, list of sections and list of files.

    Async
  • Similar to Discussions, Knowledge can be organized using Tags and starring.

    Async
  • A user can trigger a list of Discussions by simply typing #d anywhere in the content. Similarly, a user can type #k to trigger a list of Knowledge docs.

For me personally, Async's Knowledge features is as important as Discussions. Discussion is a focused and asynchronous but transient form of communication around Issues. Knowledge is a form of preservation of our team's knowledge that is meant to be shared and collaborated on. In our team, we have a rule of saving knowledge-worthy information from Discussion to Knowledge, since Discussion is transient and meant to be deleted when resolved. It's understood that a Discussion's author will save knowledge-worthy information to an existing or new Knowledge doc before the author deletes a Discussion.

We write all of our Articles launch as a Knowledge document and ask each other to proofread. We store all of our knowledge related to deploying and upgrading our AWS infrastructure as Knowledge. We keep important snippets of JS code for quick reference in Knowledge. We have numerous lists, such as important people, websites, contacts, posts, podcasts as Knowledge docs. Kelly and I have personal Knowledge docs related to our homestead projects.