Chat is not documentation
You see it in both open source projects and in companies. A chat tool promises to be the go-to place for collaboration, but falls short of the promise. One of the common ways to realize it’s not all you were told is a story like Doug Bowman shared:
Earlier tonight, a client said they couldn’t find information about colors, fonts, conversations about marketing plans and dates, and other pointers I had shared with them. Everything was shared via Slack sometime last year, as that’s what they insisted on using.
I checked their Slack a bit ago, and every single channel was empty. Every resource I shared, every message and reply, every color and logo file… all hidden and held ransom from them (and me) unless they start paying.
The problem isn’t just with Slack, although Slack is not a great choice for open source communities. The true problem is that chat tools are not documentation. Chat is somewhat ephemeral. When you try to use it as a long-term resource — even if you have years of logs — it gets rough.
Documentation should have these attributes:
- Organized. Individual documents should be arranged in a way that makes sense to the reader. This is easy to do when the body of documentation is small. As it grows, you need a librarian. But chat systems don’t do that. The content doesn’t follow a planned layout, it ebbs and flows with conversation.
- Updated. Okay, most documentation fails in this regard. But in general, it’s easier to keep up to date than old chat messages. This is particularly true when it’s someone else’s chat message.
- Cross-referenced. Most documentation platforms make it easy to link to other documents. That’s a little more challenging in chat systems. It’s possible, but not always straightforward.
- Coherent. This is similar to “organized’, but more about the flow within a particular document.
- Contextualized. It should be easy to see what comes before and after the specific content you searched for. Some chat tools make that easy, others don’t. And the chat style of typing many short messages means seeing the context of a particular message can be difficult.
This posts featured photo by Volodymyr Hryshchenko on Unsplash.
