Happy to see 2023 kicking off with an emphasis on canceling ineffective meetings (access doesn't always imply action) and the benefits of a written/document culture. Written/document culture can be a powerful mechanism to build shared understanding, expose assumptions, and help new team members learn the Why behind the How.
However, what documents don't do is self-organize themselves. I've found it helpful to provide scaffolding for those documents to be discoverable and temporally accurate.
Mastodon Source 🐘
Discovery: The lowest cost doc writing is "Create New" in whatever tool you're using. This typically creates a document with a semi-random, sometimes slug-including, URL in a flat space. Sometimes there are labels to logically group documents, assuming the author already knows the set of labels and their out-of-band definitions. I usually don't know the universe of labels and which are most betterer than other labels.
These documents are a thousand points of disconnected lights. Wire them up!
Mastodon Source 🐘
I proactively create a hierarchical virtual space to make it easier for related documents to be near each other. For instance, by project, by state (Archived, In Progress, Discarded), by YY/MM, etc. I spend some time trying to corral existing documents into that structure. I try to minimize the information discovery cost to a single event, rather than a series of ongoing searches in hopes we can find "that design doc from last year that has all the information".
Mastodon Source 🐘
Temporally accurate: I've found this to be a lot more challenging. In the process of corralling documents, I've found documents with open comment threads, no comments (was it even reviewed?), and historical dates. This is all good information...or noise, depending on what actually happened.
Mastodon Source 🐘
I include an explicit metadata block that includes document status. Something like ADR documents: https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md. Did the team chat about this and discard it, are we still talking about it (and if so, when did we do so last), is it a fantastic idea that is approved? Implemented?
I'm still struggling with this one and I'd like to learn more about ADLs (https://github.com/joelparkerhenderson/architecture-decision-record) in the real world to see if it could help.
Mastodon Source 🐘
TL;DR; Written/document culture is generally beneficial, supports asynchronous communication, and I've found it to be more effective with additional structure.