Communication can bring order or chaos. When we have a software project that involves business-level stakeholders and multiple software development teams, placing the right communication in the right place skyrockets in priority.
Communicating extensive, highly technical information should happen where the target audience will find it the most natural to interact with the information. If the interaction is not natural or feels forced, it won't happen.
I recently needed to engineer a spec for a new algorithm that drives main features on our client's platform. Writing this up required an outline for the previous algorithm, the rationale for moving to a new process, and details for how the new iteration works.
Such a write-up is high on the technical scale for the sake of the developers. A business-level outline would list the effects and outcomes of each algorithm, but we wouldn't want to put a lot of technical details for that target audience.
So, once the technical spec is ready to share with other project personnel, where should we post it?
On this project, we regularly use a few communication platforms: Slack, Notion, and GitHub. In this case, a GitHub wiki page was the most appropriate medium for a technical spec designed for a technical audience.
Slack
Slack is great for streams of communication, i.e. things that are important to notice right now but probably won't be important in a day or two.
We could think of Slack as a more convenient phone call, a digital medium for conversations similar to just picking up the phone, calling someone, and discussing the details. And, in most cases, we have a record of the discussion, like a more immediate email.
But communication via Slack is inherently time-based for collaborative discussion, so it usually is not appropriate to drop a highly technical, detailed spec in a channel. Discussion about the spec could happen there, but it's not the place to leave the spec itself.
I have seen some projects use channel "pins", where certain documents are pinned for reference. Of course, the UX there is limited and doesn’t offer a lot of space to pin a lot of things.
Notion
Notion provides a more editorial workflow. Within a workspace, pages can have outlines, calls to action, the ability to comment, and other collaborative features.
This is a good medium for the business-level users and stakeholders on the platform. But developers will not regularly interact here.
A lot of communication from the business side represents various levels of action readiness. Developers should not be expected to efficiently sort through which pages are ready for development, which ones require their attention/discussion, and which ought to be ignored for a time.
GitHub
That left us with GitHub, which, for developers on the project, should have been a quite natural place to see specs. There, the spec could be closely associated with the code that will eventually enact the algorithm.
Code reviewers can have all they need when reviewing pull requests to evaluate if the code changes sufficiently reflect the spec. Discussion posts can get all of the developers on the same page.
Each project should have one or two stakeholders who can be given access to some of the technical details. They can be added as outside collaborators in GitHub and provided access to the wiki and discussion posts.
Many tools can bring business and technical project personnel onto the same page, such as Confluence, or Dropbox Paper. In each of those platforms, though, the question will remain: “how do I get my target audience to interact naturally with the communication?”