Let me tell you a story about a time things got… complicated. At a previous job, we had a pretty standard setup: Slack for real-time chat, Jira for tracking tasks, and Asana for higher-level roadmap planning. We had our rhythms, and importantly, we had a shared understanding of how we used each tool.

Then, a new VP joined, let’s call him Bob. Bob started using Asana in a way we weren’t accustomed to – assigning tasks to me with due dates, but without any direct conversation about them. I only discovered these assignments days after the deadlines had passed, buried within a flood of other notifications in my email inbox.

I remember feeling that double-whammy of embarrassment for missing deadlines I didn’t know existed, and the frustration at being blindsided by work and having yet another place to check for assignments alongside Jira. Bob was understandably frustrated too because these were tasks that were important to him and he wasn’t seeing the results he expected.

What was happening? Bob was essentially using Asana, which our team primarily treated as a documentation/planning system requiring users to pull information, as if it were a real-time communication system designed to push urgent tasks and grab immediate attention. Our established working agreement about how we used Asana wasn’t clear to him, and his actions fractured our communication flow.

This experience hammered home a critical lesson: understanding the fundamental nature and intended audience of the systems we use – whether for documentation or communication – isn’t just about tool preference; it’s essential for preventing frustration, avoiding missed expectations, and ensuring that crucial information actually lands with the right people at the right time.

Let’s dive into what makes documentation and communication systems different, and how using them intentionally can help us avoid “Bob” situations and build smoother, more effective teamwork.

Documentation Systems: The Persistent Memory Keepers

Think of your documentation systems as the team’s long-term, stable memory, specifically curated for people who will need that information in the future. This includes your future self (you’ll thank you!), teammates joining later, or anyone needing historical context down the line. Tools like Confluence (or any wiki), Google Docs, Github (for code, PRs, issues), Jira (or other issue trackers), and Figma are built to store information that needs to endure and be referenced over time by this future audience.

The superpower of documentation is its ability to capture decisions, context, and knowledge persistently. Its primary audience exists after the moment the information is created or discussed. A great documentation system is:

• Stable over time: Links work tomorrow and next year.
• Discoverable: Future readers can find what they need when they go looking for it.
• Purpose-built: Agreed upon for specific types of information needed for later reference.
• Persistent: Information stays put for that future audience.

Documentation systems excel at providing detailed answers to “Why did we decide this?”, “How does this system work?”, or “What’s the history of this feature?”. They are designed to be frequently read or pulled by someone seeking information from the past. Crucially, because their audience is often not the group actively collaborating right now, they are not designed to demand your immediate, real-time attention the way a ringing phone or a chat notification does.

But if documentation is for the future and requires people to pull information, how do we handle things right now and get the right people’s attention when we need it?

Communication Systems: The Real-Time Connectors

Now, consider communication systems. These are the tools crafted for immediate interaction and getting information to people who are present and available right now. Their primary audience is the team as it exists in the current moment. We’re talking about Slack, Microsoft Teams, Zoom, and (maybe) email.

The main goal here is real-time exchange and getting people’s attention focused on the current conversation among the present team members. Their core strengths are:

• Real-time Information Push: They notify the present audience when something needs attention now.
• Shared Context (in the moment): They help teams align quickly on current tasks among those currently engaged.
• Knowing Where to Look for Urgency: When everyone uses the agreed communication tool, the present team can stay focused and respond quickly.

This ability to push information and grab attention in real-time for the present audience is their defining characteristic. They optimize for the current conversation.

However, relying only on these fast-moving streams, especially when you need information to last or be easily referenced by that future audience, presents significant challenges. Communication systems are designed for unstructured, ongoing conversation. This means the evolving understanding captured within them is rarely synthesized or neatly summarized. Participants are often required to hold the context of the conversation primarily in their heads.

Trying to use this kind of system for documentation leads to problems because:

• Information is inherently spread out and disorganized across many messages.
• Corporate retention policies will automatically purge messages over time, removing knowledge and context from the system.
• Getting meaningful information requires reconstructing context by sifting through previous messages, understanding who was involved, and what the shared understanding was at that exact moment.
• It’s difficult to remove or clearly mark incorrect or outdated information, as every message contributed to the conversational flow at the time, even if its content is no longer accurate.

Trying to make communication systems serve as documentation results in fragmented information, potentially wrong or outdated answers, and slow, painful reconstruction of past knowledge, all of which will eventually vanish from the system! This significantly increases the likelihood of misunderstanding critical details later on. Documentation systems solve these problems by consolidating and organizing information, providing stability and persistence, and offering clear ways to update or flag content as stale.

The Friction: The Mistake of Expecting Attention Where It Doesn’t Live

Documentation systems are not meant for real-time communication or attention-getting. When we try to use them this way, we create friction and frustration.

This is precisely why trying to force documentation systems to serve as communication systems creates major friction and leads directly to frustrations, missed expectations, and fractured communication flows. The biggest friction happens when we try to use a documentation system (built for a future audience) to get the attention of the present audience right now.

A common example is adding a crucial comment or update to a wiki page or a ticket and assuming the relevant people will see it immediately. While comments on documentation are great for capturing context within that document for anyone who reads it later, they are not effective mechanisms for demanding the present team’s attention right now.

Why does this fail? Because documentation systems are optimized for future discovery, not present interruption. They don’t have the built-in “push” notifications and attention-grabbing design of communication tools aimed at the here-and-now. Expecting an urgent response to a documentation comment is fighting against the fundamental nature of the tool and its intended audience focus. It forces your present audience to constantly pull for updates by actively checking documents, rather than having important needs pushed to them. This is where expectations are missed and information gets lost in the lack of directed attention for the people who need to see it now.

Finding Harmony: Document There, Direct Attention Here

The good news is that these systems work together beautifully when used for their intended purposes. The most effective practice is simple, but powerful:

• Capture your detailed information, decisions, and context in the documentation system. This is where the persistent, discoverable source of truth belongs, ready for that future audience (or anyone who pulls it up later).
• Then, use your communication system to notify the relevant present audience that their attention is needed regarding that documented information. Send a clear message in the team’s communication channel: “Hey team, I’ve added the finalized proposal and technical details to the design doc [link here]. Please take a look and add your sign-off comments on the doc by EOD tomorrow.”

This strategy leverages the strengths of both systems: the documentation system provides the stable, detailed record for anyone seeking it (now or in the future), and the communication system provides the necessary push to get the present team’s attention on it quickly. You are using the communication tool’s ability to grab attention to drive people to the documentation tool’s rich information, effectively bridging the gap between the present need and the persistently stored detail.

Bringing It All Together: Intentional Use for Better Outcomes

Documentation systems and communication systems are both indispensable, but they serve different purposes: persistence for the future versus presence for the now.

By understanding the fundamental nature and intended audience of each – that documentation is for stable reference by future readers (pulling information) and communication is for real-time interaction and getting the present team’s attention (pushing information) – we can avoid the pitfalls of frustration and missed expectations.

Using the simple best practice of documenting details in your stable systems and using your attention-grabbing communication tools to notify colleagues about them creates a powerful synergy. And fostering a team-wide understanding of this distinction, coupled with intentional communication practices, is perhaps the most impactful change we can make. It ensures that critical information is not only recorded for posterity but also effectively shared and seen by those who need to act on it now, leading to smoother projects and happier teams.

Ready to leave the chaos and frustration of lost information behind? It starts with a simple practice: document for the future, communicate for the present, and always link the two with intention. Embrace the power of using each tool for its superpower, and watch your team’s information flow transform.

Photo by Prometheus 🔥 on Unsplash