"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."
"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 were a handful of issues we were running into: 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"
Documentation received many comments in a developer productivity survey, prompting focused cleanup work. Migration from Confluence to Notion left many outdated pages that appeared obviously wrong and created a bad smell around other documentation. Teams had inconsistent rules for what belonged in Git-managed files versus Notion, producing duplication and a tendency to add N+1 copies instead of consolidating. Many recent hires were uncertain about ownership or permission to update files. Notion AI became the main surface for content, making inaccurate snippets harmful. Notion API limitations hindered programmatic verification, discovery, archiving, and view analytics. A policy was adopted to address these problems.
Read at Lethain
Unable to calculate read time
Collection
[
|
...
]