I hate Confluence, but I love documentation.

Confluence Sucks

It’s slow.

  • So slow.
  • Why does it take seconds to interact after the page loads?

It’s more than I need.

  • Layouts / Tables / Designs
  • Labels and Gizmos
  • Embedded Google Docs
  • … then what’s the point at all?
  • Complicated Access Permissions
  • Pretty-formatting links
Confluence “Features”

The bad features are like candy.

  • When you see a feature, you use it.
  • Sometimes less is more.

Multi-User Editing - Gah!

  • Editing a doc with multiple users is the worst.
  • “Edit in Google Docs, copy to Confluence”

Why am I so angry?!

The tool just keeps getting in my way.


API Docs

Haven’t we all picked platforms based on this?

Github Docs

Solutions and Planning

  • Reviewing a proposed feature.
  • Iterating on a design.
  • Faster than coding it.
Github Review of Proposal

Standards Docs

  • Force you to think through a problem.
  • More valuable than tooling.
  • And often lead to tooling!

And so much more…

  • Onboarding
  • Processes
  • Runbooks
  • Progress
  • Project Management
  • Planning and Coordination

Why is it to hard to do the right thing?

Documentation fails when it’s not kept up to date.

Bad tools increase the friction to update documentation.

Let’s make documentation fun again?

What I want.

Simple diffs

A simple API


  • https://commonmark.org/
  • It forces you to think linearly.
  • Complicated data should use separate pages, not layouts.

Mobile Friendly

Why the hell is this so hard?


Automatic Formatting

  • Use Prettier or something.

Diagrams as first-class citizens

Collaborative Editing

Build something with this: https://blog.cloudflare.com/introducing-workers-durable-objects/

“Present” any doc without prep.



✔️ Confluence

What else?

plz help.

I genuinely hate Confluence.

I hate it so much.

// reveal.js plugins