Markdown + AI: The Communication Protocol That Changes Everything

Today at work Ary Sharma and I had a discussion about why I'm pushing our team to use Markdown. This summer at GE Aerospace Ary's was part of a mission based team working to leverage AI to better use the data soloed into different systems like Confluence. Anyway, I mentioned all the tools I've used in the past but didn't have a concise explanation. We had a discussion on why I believe Markdown is a better format for Human and AI collaboration, but that even before AI it was already a better long-term knowledge management. This post is any attempt to better frame that conversation. Thanks, Ary!

I've spent over two decades taking notes, and I can tell you this with absolute certainty: 2025 is the year human-AI collaboration becomes the defining factor for progress—and Markdown is the universal language that makes it work.

But this realization didn't come overnight. It's the culmination of years of struggling with note-taking systems, knowledge management tools, and finally discovering that the simplest format might just be the most powerful.

TLDR

If you just want to learn markdown go to https://commonmark.org/help/. It has a great cheat sheet and amazing 10 minute tutorial to walk you through the basics.

Continue reading if you want to learn how I got here.

My Note-Taking Evolution: Two Decades of Trial and Error

Over the past 20+ years, I've experimented with every note-taking and knowledge management system imaginable. Here's my complete journey through the evolution of productivity tools:

1. Early 2000s: TXT Files Everywhere

Back in the early days, I was that developer with .txt files scattered across every folder. Random thoughts, code snippets, commands I'd inevitably forget—all stored in simple text files with names like notes.txt, stuff.txt, and the ever-popular todo.txt.

The beauty was in the simplicity. No formatting to worry about, no proprietary formats, no subscription fees. Just me, a text editor, and whatever thoughts needed capturing.

2. Mid-2000s: The SharePoint Enterprise Experiment

At work, we tried SharePoint for team documentation and knowledge sharing. This was my first encounter with "enterprise-grade" knowledge management. While it had powerful features for collaboration, document management, and workflows, it felt heavyweight and cumbersome for actual daily use.

The interface was clunky, search was unreliable, and it required too much upfront structure and planning. You had to think about information architecture, permissions, and content types before you could just... write something down. Classic enterprise software: powerful but painful.

3. 2008: The Dropbox Revolution

When Dropbox launched in 2008, it felt revolutionary. Finally, my scattered text files could sync across machines automatically. No more USB drives, no more emailing files to myself. I organized everything in a clean Dropbox folder structure, thinking I'd solved the sync problem forever.

4. 2009-2010: The Google Wave Dream (and Nightmare)

Then came Google Wave in 2009—hands down the best collaborative tool Google ever built. Real-time collaboration, threaded conversations, the ability to embed rich content. For that brief, shining moment, I thought I'd found the perfect system.

And then Google killed it in 2010, after just months of public availability. Everything had to be backed up and migrated. Again.

Note: Google Wave was discontinued, but you can learn about its legacy through Wikipedia or try Apache Wave, the open-source successor.

5. 2010s: The Screenshot Experiment: When "Later" Never Comes

Somewhere in this timeline, I even tried a tool that took screenshots of my desktop every 10 seconds. The idea was brilliant: capture everything I was doing, so I could write guides later based on my actual workflow and include screenshots from the process.

The problem? Later often never came. I'd have thousands of screenshots and no time to process them into useful documentation. The friction was too high, and the signal-to-noise ratio was terrible. I remember I stopped doing this sometime before 2010 before I started blogging but not sure when.

6. 2012: The Google Drive Migration

When Google Drive launched in 2012, it seemed like the logical next step. Better integration with Google's ecosystem, more collaboration features than Dropbox. I migrated everything from my Wave backups and Dropbox files.

Great for collaboration, but terrible for code snippets and technical notes. The rich text editor kept mangling my carefully formatted code examples.

7. 2015: The First Markdown Breakthrough

Tired of fighting with Google Drive's rich text editor mangling my code snippets, I created a repository on GitHub called "toolbox." I was hitting storage limits on Dropbox anyway, so this felt like killing two birds with one stone.

This was my first real experiment with Markdown as a documentation format. No more wrestling with formatting—just write in plain text with simple syntax for headers, lists, and code blocks. The files were readable both in raw form and when rendered by GitHub.

I could git clone my entire knowledge base anywhere, home machine, work machine, I ended up with a toolbox I could always take with me.

But I wasn't quite there yet. I was still experimenting with other tools...

8. 2016-2018: The Notion Experiments

I tried Notion v1.0 when it launched in 2016, then gave Notion v2.0 a serious shot in 2018. Beautiful interface, powerful databases, infinite customization possibilities.

But it was slow, over-engineered for my needs, and I spent more time configuring the perfect setup than actually taking notes. Classic productivity tool trap.

9. 2020: The Obsidian Exploration

When Obsidian launched in 2020, the linking and graph features seemed promising. The idea of a "second brain" with interconnected notes was compelling.

I never used the graph, I found searching better than trying to navigate the visual representation. It demos amazing, but that's not how I think. I spent more time adding links and tags than actually writing. Then never quite using those tags and notes.

10. 2020 to Present: The Confluence Black Hole

We use Confluence, and it perfectly illustrates why traditional knowledge management systems can be challenging. Due to the sheer amount of data siloed in our Confluence instance and fine-grained search is non-existent means data can go in but not come out, leading to frustration where you know the data exists but can't find it.

But here's where the story gets interesting: Getting that data out of Confluence and into a RAG (Retrieval-Augmented Generation) system to use AI was actually Ary Sharma's mission-based project this summer at GE Aerospace. His team of 3 joined my team for the summer and worked to break down these data silos and make our institutional knowledge actually accessible through AI.

11. The Others

I'm not even going to go into detail about all the other tools I only picked up for a couple of days, but they include the likes of OneNote, Foam, Evernote, Box, and multiple Wiki platforms.

12. 2020+: The Return to Simplicity - Markdown in a Private Repo

Eventually, I kept coming back to that same 2015 toolbox repository. It just worked, it was never down, out of space or hard to find stuff. I approached it with more wisdom. I refined my approach: a private repository with markdown files organized by date and topic, using the same principles but with better consistency.

I use grep and standard search tools to find anything. I didn't need fancy indexing or web hosted solution search. Basic text search across a folder of markdown files was faster and more reliable than any sophisticated system I'd tried.

The key insight: I needed a digital trail I could follow months later when I was trying to remember how something worked or when I did something. Markdown files provided exactly that—simple, searchable, version-controlled breadcrumbs.

The pattern was always the same: find a tool, build a system, watch it become inadequate or disappear, then migrate everything again. After two decades, I realized the problem wasn't the tools—it was my expectation that a tool could solve what was fundamentally a workflow problem.

The Agentic Workflow Revolution

Fast forward to 2025, and something fundamental has shifted. We're not just using AI for one-shot questions anymore. The real power lies in the agentic workflow loop:

1. Human intent → Clear problem definition or goal
2. AI processing → Analysis, suggestions, initial solutions
3. Collaborative refinement → Human feedback, iteration, improvement
4. Shared context → Both parties build on accumulated knowledge
5. Next iteration → More sophisticated problems and solutions

This isn't about getting better answers from AI—it's about creating a collaborative thinking process where both human and AI contribute their strengths over time.

The magic happens in that shared context layer. Unlike chat interfaces where conversations disappear into the void, markdown creates persistent, versioned, searchable collaboration artifacts.

Markdown as the Universal Protocol

Here's why Markdown has emerged as the perfect format for human-AI collaboration:

Machine Readable + Human Readable

Both humans and AI can process Markdown natively. You don't need special parsers or complex formatting rules. It's structured enough for machines to understand and simple enough for humans to write quickly.

## Problem Statement
Need to optimize database queries for user dashboard

## Current Issue
- Loading time: 3.2 seconds
- Query count: 47 per page load
- Memory usage: 240MB peak

## Proposed Solutions
1. Implement query caching
2. Add database indexes
3. Reduce N+1 queries

Persistent Context

Unlike chat interfaces, markdown files create lasting collaborative artifacts. Your conversation with AI becomes a document that you can revisit, reference, and build upon weeks later.

I've had Claude Code sessions where we worked on complex refactoring over multiple days. Because everything was captured in markdown files, we could pick up exactly where we left off, with full context intact.

Version Controlled Collaboration

When you store your human-AI collaboration in markdown files within a git repository, you get something revolutionary: the complete history of how problems were solved.

You can see how your thinking evolved, which AI suggestions you accepted or rejected, and what the final solution looked like. This creates a searchable database of your own problem-solving patterns.

Structured Thinking

Markdown forces clarity in both directions. When you need to explain a problem to AI, the act of writing it in structured markdown makes you think more clearly about what you're asking.

Similarly, AI responses in markdown are more organized and actionable than free-form chat responses.

The Meta Aspect: This Blog Post

The irony isn't lost on me that I'm writing a blog post about markdown-AI collaboration using exactly this process. This post started as a markdown file where Claude Code and I iterated on structure, content, and examples.

The collaborative process created a better final product than either of us could have produced independently.

Building Persistent Context

Every session builds on previous work. When I return to a project weeks later, the markdown files contain our collaboration history as these artifacts it can read get better context. Claude Code can quickly get back up to speed by reading what we've previously produced.

This compound effect means our collaboration gets more sophisticated over time, rather than starting from scratch each session.

Why This Matters for 2025 and Beyond

Individual Productivity: The 10x Multiplier

When you nail the human-AI collaboration loop with markdown, code or anything where you both contribute and refine, the productivity gains are genuinely transformative. You're not just getting faster answers—you're creating a thinking partnership that gets smarter over time.

I can tackle complex architectural problems, debug subtle issues, and explore new technologies faster than ever before. The key is that building that shared context that lets us build on previous work.

Knowledge Management: Searchable AI Collaboration History

Your markdown files become a searchable database of every problem you've solved with AI assistance. Need to remember how you optimized that React component six months ago? grep through your collaboration history.

This is knowledge management that actually works because it's based on the same tools you already use for code.

Future-Proofing: Portable Across AI Systems

Markdown files work with any AI system. Whether you're using Claude, GPT, Copilot, or whatever comes next, your collaboration format remains constant. You're not locked into any particular platform or interface.

Build the Habit

Start small:

• Pick one project for markdown-AI collaboration
• Create a simple structure and stick to it
• Focus on persistence over perfection

Evolve gradually:

• Add more structure as you see what works
• Develop your own collaboration patterns
• Share successful formats with your team

4. Leverage Standard Tools

Search and discovery:

# Find all discussions about database optimization
grep -r "database" projects/

# See what you worked on last month
ls -la daily-notes/2025-07-*

# Track decision evolution
git log --oneline -- projects/database-optimization/

Common Pitfalls (That I Hit So You Don't Have To)

Over-Engineering the System

I spent weeks building elaborate folder structures and naming conventions. The truth is, simple organization plus good search beats complex taxonomy every time.

Keep it simple: Date-based organization and descriptive filenames will get you 90% of the way there.

Treating AI Like a Search Engine

The biggest mistake is using AI for one-shot questions instead of building collaborative context. If you're not creating persistent artifacts from your AI interactions, you're missing the real value.

Ignoring Version Control

Your collaboration history is valuable. Seeing how your thinking evolved over time, which approaches worked, and what dead ends you explored—that's all useful context for future problems.

Commit OFTEN, AI can add too much, delete something it shouldn't. By committing often or even just doing git add . acts like a video game save point you can always go back to.

The Future of Human-AI Collaboration

We're still in the early days of figuring out how humans and AI work best together. But I'm convinced that the teams and individuals who master the agentic workflow loop will have a massive advantage.

Markdown isn't just a formatting language—it's becoming the universal protocol for human-AI collaboration. It's simple enough to write quickly, structured enough for AI to process effectively, and persistent enough to build lasting value.

The goal isn't to replace human thinking with AI thinking. It's to create a collaboration format where both human creativity and AI capability can compound over time.

The Bottom Line

After two decades of note-taking evolution and months of intensive AI collaboration, I've reached a simple conclusion: the format matters as much as the content.

Markdown has emerged as the universal language for human-AI collaboration because it maximizes the value of the agentic workflow loop. It's readable by both humans and machines, persistent across sessions, version-controlled by default, and searchable with standard tools.

The teams and individuals who figure this out first will have a significant advantage in 2025 and beyond. Not because they're using AI better, but because they're collaborating with AI in a way that creates compound value over time.

Start simple: create a markdown file, ask AI to help with a problem and iterate on the solution together. Do this consistently, and you'll discover what I've learned: the future belongs to those who can think with machines, not just ask them questions.

Now stop reading about it and start building your own human-AI collaboration protocol. Your future self will thank you.