# Refactoring internal documentation in Notion

DevFeed: [Refactoring internal documentation in Notion](<https://devfeed.tech/articles/refactoring-internal-documentation-in-notion-35689.md>)

Original publisher: [Read original article](<https://lethain.com/refactoring-internal-docs-notion/>)

Published: 2026-02-05T14:00:00Z

Content type: article

Language: en

Sources: [Will Larson - Irrational Exuberance](<https://devfeed.tech/sources/will-larson-irrational-exuberance.md>)

Topics: [Notion](<https://devfeed.tech/topics/notion.md>), [Refactoring](<https://devfeed.tech/topics/refactoring.md>), [code productivity](<https://devfeed.tech/topics/code-productivity.md>), [Documentation](<https://devfeed.tech/topics/documentation.md>), [API](<https://devfeed.tech/topics/api.md>)

Tags: [ai](<https://devfeed.tech/tags/ai.md>), [api](<https://devfeed.tech/tags/api.md>), [content](<https://devfeed.tech/tags/content.md>), [developer-productivity](<https://devfeed.tech/tags/developer-productivity.md>), [documentation](<https://devfeed.tech/tags/documentation.md>), [git](<https://devfeed.tech/tags/git.md>), [notion](<https://devfeed.tech/tags/notion.md>), [refactoring](<https://devfeed.tech/tags/refactoring.md>), [survey](<https://devfeed.tech/tags/survey.md>)

## AI overview

A writeup of efforts to improve an organization's internal documentation after a migration from Confluence to Notion. It examines stale and duplicated pages, unclear ownership, Notion AI usage, and API limitations, then describes policies focused on reducing duplication and stale content and optimizing documentation for Notion AI.

## Source excerpt

In our latest developer productivity survey, our documentation was the area with the second most comments. This is a writeup of the concrete steps I took to see how much progress one person could make on improving the organization's documentation while holding myself to a high standard for making changes that actually worked instead of optically sounding impressive. Diagnosis There were a handful of issues we were running into: We migrated from Confluence to Notion in January, 2025, which had left around a bunch of old pages that were "obviously wrong." These files created a bad smell around our other docs, as folks felt like things weren't well maintained. We had inconsistent approach to what we documented in Git-managed files versus managing in Notion. This led to duplication. Duplication meant that it felt safer to create an N+1th version, rather than debugging why N versions already existed. We've had a bunch of new folks join over the past year, who weren't sure if they were empowered to update documentation or if someone else was managing any given file We started using Notion AI as the primary mechanism for exposing content, which meant that hierarchical organization was less important, and that having inaccurate snippets was harmful even if they were tucked away into a quiet corner This was combined with a handful of interesting limitations in Notion itself: You cannot tell if a non-wiki page is verified or not via API. You can tell if a wiki page is verified via API, but no one uses wiki pages You cannot retrieve all pages in a Notion Teamspace via API, you instead have to manually take list of the top-level pages in that Teamspace, and find the children from those pages There is no "archive" functionality in Notion that allows you to exclude a document from search results There is no programmatic visibility into views or usage of a page via API except for how recently it was edited Policy The policy we adopted for addressing the above diagnosis was: Optimi