🚀 Executive Summary
TL;DR: The article addresses the pervasive ‘Empty Page Syndrome’ in documentation platforms like Notion and Confluence, where creating pages provides a false sense of organization but leaves critical information missing, leading to significant ‘documentation debt’. It proposes a multi-pronged solution, including immediate behavioral changes like the ‘Two-Bullet Rule’, automating documentation scaffolding with templates and API integrations, and conducting ‘Documentation Sprints’ for a hard reset of existing knowledge bases.
🎯 Key Takeaways
- Implement the ‘Two-Bullet Rule’ for new pages, requiring immediate addition of ‘Purpose’ and ‘Next Action’ to prevent empty documentation and foster mindful content creation.
- Automate documentation scaffolding by leveraging platform templates (e.g., Notion, Confluence) for common document types like ADRs and Post-Mortems, and integrate with project management tools (e.g., Jira API) to automatically create pre-filled pages based on triggers.
- Conduct a ‘Documentation Sprint’ to address extensive documentation debt, enforcing a temporary ban on new pages while dedicating engineering time to fully flesh out or delete existing underfilled/irrelevant documentation.
Stop treating your documentation platform like a digital graveyard. Here’s a no-nonsense guide from the trenches on how to create documentation that actually gets used, not just created.
How I Cured My Team’s ‘Empty Page Syndrome’ in Notion & Confluence
I remember it like it was yesterday. It was 3 AM, and PagerDuty was screaming about a cascading failure in our authentication service. The on-call engineer was on a flight, so it fell to me. I SSH’d into the jump box, heart pounding, and navigated to our Confluence space. I found the page: “Runbook: prod-auth-svc-03 Failure.” I clicked it, full of hope. And what did I find? A title. And nothing else. Just a beautiful, hopeful, utterly useless empty page created six months prior. We spent the next two hours fighting a fire that a ten-minute runbook could have prevented. That was the day I declared war on empty pages.
The ‘Why’: The Dopamine Hit of False Organization
Let’s be honest with ourselves. This isn’t about being forgetful. It’s about psychology. Creating a new page titled “Q4 Database Sharding Strategy” or “Onboarding Guide for New Hires” feels productive. It gives you a tiny dopamine hit, a feeling of having organized a problem. But you haven’t done the work. You’ve just created a digital IOU for your future, more-motivated self—a self that rarely shows up. You’ve built a beautiful, empty filing cabinet. The problem is that this “documentation debt” is just as dangerous as technical debt, and as my 3 AM war story shows, it can bite you when you least expect it.
The Fixes: From Battlefield Triage to Strategic Overhaul
You can’t fix a cultural problem with a single tool. You need a multi-pronged attack. Here are the three levels of engagement I’ve used to turn our documentation graveyards into living, breathing knowledge bases.
Level 1: The Quick Fix – “The Two-Bullet Rule”
This is the immediate, tactical change you can implement today. It’s simple: You are not allowed to create a new page without immediately adding, at minimum, two bullet points or one complete sentence. No exceptions.
The first bullet/sentence should state the Purpose. The second should state the Next Action.
For example, instead of just a title, the page “Runbook: prod-auth-svc-03 Failure” should have immediately been populated with:
- Purpose: A step-by-step guide to diagnose and restart the auth service when it becomes unresponsive.
- Next Action: Add the link to the Grafana dashboard and the command to check log outputs.
This tiny bit of friction forces you to think for five seconds about why you’re creating the page and what its value is. It breaks the “create and abandon” cycle cold.
Pro Tip: This is a team discipline. Announce it in your team’s chat. If you see a new, empty page from a teammate, gently remind them of the rule. It’s about building a habit, not shaming anyone.
Level 2: The Permanent Fix – “Automate the Scaffolding”
The next level is to remove the friction of starting from scratch. Engineers hate blank pages. So don’t give them any. Use the template features in Notion, Confluence, or whatever you use. Create templates for your most common documents:
- Architecture Decision Records (ADRs)
- Incident Post-Mortems
- Service Runbooks
- Project Kick-off Docs
A good post-mortem template doesn’t just have headings. It has prompts: “What was the customer impact?”, “Link to the monitoring dashboard during the incident:”, “What was the root cause?”, “What are the action items to prevent this? (Assign owner and due date)”.
You can take this even further by integrating it with your project management tools. For example, using the Jira/Confluence or Notion APIs, you can set up an automation:
Trigger: A new Jira ticket of type ‘Bug’ with priority ‘Highest’ is moved to ‘In Progress’.
Action: Automatically create a page in Confluence using the ‘Incident Post-Mortem’ template and link it back to the Jira ticket.
Here’s a conceptual pseudo-script for what that might look like with a webhook:
# Pseudo-code for a webhook listener (e.g., AWS Lambda, Google Cloud Function)
function handleJiraWebhook(request) {
const jiraTicket = request.body;
if (jiraTicket.issue.fields.issuetype.name === "Bug" &&
jiraTicket.issue.fields.priority.name === "Highest") {
const ticketId = jiraTicket.issue.key;
const summary = jiraTicket.issue.fields.summary;
const templateId = "12345"; // Your Confluence Post-Mortem Template ID
// Call the Confluence API to create a new page
createConfluencePageFromTemplate(
space = "POSTMORTEMS",
title = `Post-Mortem: ${ticketId} - ${summary}`,
parentPage = "2024 Incidents",
templateId = templateId
);
// Call the Jira API to add a comment with the link
addCommentToJiraTicket(ticketId, "Post-mortem doc created at: [link]");
}
}
Level 3: The ‘Nuclear’ Option – “The Documentation Sprint”
Sometimes, the graveyard is too big to fix incrementally. The search results are cluttered with empty pages, and nobody trusts the documentation anymore. It’s time for a hard reset. I call this the “Documentation Sprint.”
For one full sprint (or just one week), you enact two radical rules:
- No NEW pages may be created. Zero. None.
- Every engineer must dedicate 2-4 hours to one of two tasks: Either fully flesh out an existing, important-but-underfilled page, or delete at least 5 irrelevant/empty pages.
This is a “hacky” solution, I’ll admit. It’s brute force. But it’s incredibly effective. It forces a spring cleaning, makes the team confront the debt they’ve accumulated, and rapidly increases the signal-to-noise ratio of your knowledge base. After a week of this, people are much more mindful about hitting that “New Page” button.
Comparison of Methods
| Method | Effort to Implement | Long-Term Impact | Best For |
|---|---|---|---|
| The Two-Bullet Rule | Low (Team Agreement) | Medium | Immediate prevention of new empty pages. |
| Automate the Scaffolding | Medium (Requires setup) | High | Ensuring quality and consistency in critical documents. |
| The Documentation Sprint | High (Disruptive) | High | Clearing out a large backlog of existing documentation debt. |
Ultimately, treating your documentation like a product—with standards, automation, and occasional clean-up cycles—is the only way to win. Stop building graveyards and start building libraries. Your 3 AM self will thank you for it.
🤖 Frequently Asked Questions
âť“ What is ‘Empty Page Syndrome’ and how does it impact technical teams?
‘Empty Page Syndrome’ describes the common issue where documentation platforms accumulate numerous pages with titles but no actual content. This creates ‘documentation debt,’ leading to critical information gaps, increased incident resolution times, and a lack of trust in the knowledge base, as demonstrated by the PagerDuty incident described in the article.
âť“ How do the proposed methods for improving documentation quality compare in terms of implementation effort and long-term impact?
The ‘Two-Bullet Rule’ is low effort with medium long-term impact, ideal for immediate prevention of new empty pages. ‘Automate the Scaffolding’ requires medium setup effort but offers high long-term impact by ensuring quality and consistency in critical documents. The ‘Documentation Sprint’ is high effort and disruptive but provides high long-term impact by clearing out a large backlog of existing documentation debt.
âť“ What is a common psychological pitfall when trying to improve documentation, and how can it be addressed?
A common pitfall is the ‘dopamine hit of false organization,’ where merely creating a page title feels productive without actually doing the work. This can be addressed by implementing the ‘Two-Bullet Rule,’ which forces immediate articulation of a page’s purpose and next action, breaking the ‘create and abandon’ cycle and fostering mindful documentation habits.
Leave a Reply