Chat apps are no substitute for documentation

As a technical writer, I have a mixed opinion of chat applications like Discord and Slack. On the one hand, they make it easy to quickly get ahold of someone who can answer your questions, which is a relief if you’re struggling to gather information you need to write a draft.

On the other hand, because it’s easy to quickly get ahold of someone who can answer your questions, that convenience can implicitly incentivize folks to neglect documentation. This is true on both sides:

Jason Scott shares this mixed opinion. As he points out in Discord, or the Death of Lore:

“I have no disputes as the popularity of the places, the things that happen there, and the unquestioned vivaciousness of being the party that never seems to end and everyone wants to join.

I just happen to be the sort of person who notices there’s no decent fire exits and most of the structure is wood and there’s an… awful lot of pyrotechnics being set off.”

I feel the same way.

I wonder if the folks who have their focus time interrupted by detailed, somewhat archaic questions that require a backstory, ever wish they had documented the answer so that they could respond with a link and move on with their day.

Chat apps like Discord end up diluting the available knowledge because the content shared in them isn’t persistent, and the allure of an always-available answer breaks down when the person that could answer is no longer available. Jason refers to this as the “lore-to-knowledge transfer”:

The danger in this process, the potential lost ballast in the rise to the skies, is that the lore-to-knowledge transfer is lossy, messy, and arbitrary. Maybe those in the know want to keep the information to themselves, so it won’t be given to whoever the person or persons are who are laying down the written form. Maybe the chronicler of information has blind spots they don’t know about and not enough people to correct them. Or, more likely, you have to set the “noise filter” of the information to not go down the rabbit and rat holes of contingencies that maybe a dozen or two people will even want to know about, to the favor of that which everyone will need. The outcome is always the same: Lore loses in the long run.

The process of documenting information can break down silos (information is more available), expose blind spots in an approach (something is missing here), and enable asynchronous knowledge transfer (documentation is always online).

Etsy blogged about an interesting approach five years ago, Etsy’s experiment with immutable documentation, where they built a plugin that engineers could use within Slack to update or create documentation:

At Etsy we’ve developed a system for adding how-docs directly from Slack. It’s called “FYI”. The purpose of FYI is to make documenting tactical details – commands to run, syntax details, little helpful tidbits – as frictionless as possible.

I’d be curious to learn whether they’re still using this system, and how it has aged.