The Documentation Dilemma

I’ve spent the last few weeks obsessing over where the hell to store project documentation. Not exactly the most glamorous topic, but here’s the thing—when your docs are a mess, everything else falls apart too. Two tools keep coming up in every discussion: GitHub Pages and Notion. I’ve used both extensively, and honestly? They’re solving completely different problems.

Let me break down why this choice matters more than you’d think.

GitHub Pages: When Your Docs Live With Your Code

GitHub Pages is static site generation at its core. Push some Markdown, let Jekyll (or Hugo, or Astro—pick your poison) do its thing, and boom: a website. The repo is the source of truth. Every documentation change is a commit, which means you get blame history, rollbacks, and the entire git workflow for free.

The good stuff:

Version control is baked in. When someone deletes a section and insists it “wasn’t important,” you can prove them wrong with git log.
No servers to manage. No databases. Just HTML sitting on a CDN. It’s fast—really fast.
GitHub Actions handles deployments. Push to main, site rebuilds. Set it and forget it.
Docs live next to the code. Review a PR that changes behavior? The doc update can be in the same PR. Beautiful.

The not-so-good stuff:

It’s static. No real-time editing. No comments. Good luck getting your PM to clone a repo just to fix a typo.
You’re now running a mini tech stack. Templates, plugins, build pipelines. Congratulations, you’re now a maintainer.
Search is a pain in the ass. Either integrate Algolia DocSearch or accept that search doesn’t exist.

Last Tuesday, our PM needed to update the API rate limit documentation because we’d bumped limits for enterprise customers. She messaged me on Slack: “How do I edit the docs?” I sent her the repo link. She never followed up. The docs stayed outdated for a week until I noticed and fixed it myself. That’s the GitHub Pages experience in a nutshell.

Notion: The Workspace That Happens to Publish Pages

Notion is weird. It’s part database, part wiki, part productivity tool. You get drag-and-drop blocks, real-time collaboration (multiple cursors! actual multiplayer!), and an editor that doesn’t make you want to throw your laptop out a window.

The good stuff:

Collaboration is seamless. Someone leaves a comment, you reply, they edit, everyone sees it. Zero friction.
No build step. Write, hit publish, done. Non-technical teammates can actually contribute without learning git.
Embeds work beautifully. Figma files, Loom videos, code blocks, GitHub PRs—all inline and auto-updating.
Search is legitimately good. OCR on images, natural language queries, the works.

The bad stuff:

Vendor lock-in is real. Your docs live in Notion’s proprietary format. Export to Markdown? It’s… okay. But you’re not getting your Notion database back out intact.
Page history exists, but it’s not version control. No branches. No diffs. No meaningful audit trail.
You’re relying on Notion’s infrastructure. They have an outage? Your docs are down. Rate limits on the API? Fun times.
SEO is a gamble. Published pages get indexed, but you’re trusting Notion to handle sitemaps, canonical URLs, and all that backend nonsense.

Same scenario with Notion: PM opens the page, edits the rate limit numbers, hits publish. Done in 30 seconds. I didn’t even know she’d done it until she mentioned it in standup.

So, Which One?

If your audience is developers—API docs, architecture decision records, CONTRIBUTING files—GitHub Pages is the obvious choice. Your readers expect Markdown. They want to submit typos as PRs. The git-centric workflow isn’t a barrier; it’s the whole point.

If your audience is product managers, designers, executives, or anyone who just needs to read and occasionally edit—Notion wins. You cannot, I repeat, CANNOT convince a VP of Engineering to clone a repo and run bundle exec jekyll serve just to fix a grammatical error. It won’t happen.

Here’s What I Actually Do

I’ve settled on a hybrid approach that sounds complicated but works: use Notion for the messy, collaborative early stages. Brainstorming, drafts, “let’s get everyone’s thoughts in one place.” Once things stabilize, export to Markdown and move it to GitHub Pages. The source of truth shifts from Notion to the repo.

Is this extra work? Sure. But it gives me the collaboration benefits when I need them and the infrastructure benefits when I don’t.

Or, honestly? Sometimes I just stay on GitHub Pages and accept that non-engineers will complain. “It’s just a steep learning curve,” I tell them. They don’t buy it, but at least my infrastructure is simple.

My Recommendation

If I had to pick one today for a new project? I’d start with Notion, no question. The barrier to getting started is just too low to ignore. You can always migrate to GitHub Pages later when the docs mature and you need version control.

But if you’re documenting an API or developer tool? Skip Notion entirely. Your users are technical. They want git history. They want to fork and PR. Give them GitHub Pages from day one.

The Real Talk

GitHub Pages = docs as code. Notion = docs as a workspace. They’re different tools. Stop comparing them like they’re interchangeable. Pick the one that fits your team’s actual behavior, not the one that looks better in a screenshot.