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.”

Lethain, authored by Will Larson, offers a unique perspective on engineering management, leadership, and organizational dynamics. Developers and engineering leaders can explore topics such as team building, career growth, and organizational design, gaining insights into building high-impact engineering organizations. With thoughtful reflections and actionable advice, Lethain serves as a resource for those navigating the complexities of engineering leadership.

Irrational Exuberance

A practical guide to cleaning up organizational documentation in Notion after migrating from Confluence. The approach involved diagnosing key issues (stale content, duplication, unclear ownership), establishing clear policies (optimize for AI search, eliminate duplication, prefer version-controlled docs), and implementing automated solutions. Custom scripts were built to archive 1,500+ expired pages, identify buried current content in stale hierarchies, detect broken links, and validate key documentation. The entire effort took approximately 8 hours and required no additional team resources.

Refactoring internal documentation in Notion