Refactoring inner documentation in Notion

In our newest developer productiveness survey, our documentation
was the realm with the second most feedback.
This is a writeup of the concrete steps I took to see how a lot
progress one individual may make on enhancing the group’s
documentation whereas holding myself to a excessive commonplace for making
adjustments that really labored as an alternative of optically sounding spectacular.

Diagnosis

There have been a handful of points we have been operating into:

• We migrated from Confluence to Notion in January, 2025,
  which had left round a bunch of outdated pages that have been
  “clearly improper.”

  These recordsdata created a foul odor round our different docs, as of us
  felt like issues weren’t effectively maintained.

• We had inconsistent strategy to what we documented in Git-managed recordsdata
  versus managing in Notion. This led to duplication.

• Duplication meant that it felt safer to create an N+1th model,
  slightly than debugging why N variations already existed.

• We’ve had a bunch of latest of us be part of over the previous 12 months,
  who weren’t certain if they have been empowered to replace documentation
  or if another person was managing any given file

• We began utilizing Notion AI as the first mechanism for exposing content material,
  which meant that hierarchical group was much less vital,
  and that having inaccurate snippets was dangerous even when they have been
  tucked away right into a quiet nook

This was mixed with a handful of attention-grabbing limitations in Notion itself:

• You can not inform if a non-wiki web page is verified or not through API.
  You can inform if a wiki web page is verified through API, however nobody makes use of wiki pages
• You can not retrieve all pages in a Notion Teamspace through API,
  you as an alternative need to manually take listing of the top-level pages in that Teamspace,
  and discover the youngsters from these pages
• There is not any “archive” performance in Notion that lets you exclude a doc
  from search outcomes
• There is not any programmatic visibility into views or utilization of a web page through API besides
  for a way not too long ago it was edited

Policy

The coverage we adopted for addressing the above prognosis was:

1. Optimize for NotionAI outcomes, not guide discovery: a major majority of our Notion use
   is now through both direct hyperlinks to a selected web page, or through Notion AI, not through guide discovery.
   That implies that issues like “FAQ” pages that duplicate content material and go stale are actively dangerous,
   whereas beforehand they have been very priceless.
2. Duplication and off content material is worse than nothing: don’t write your personal information to a course of.
   Link to it as an alternative, or replace the supply doc
3. Prefer pure documentation in model management: we’d slightly hyperlink to a README in Github than
   duplicate these directions in Notion, as a result of the README is extra more likely to be saved present
4. Everyone tidies our documentation: we’d slightly be individuals who attempt to clear up a doc,
   even when we make a small mistake, slightly than somebody who leaves documentation in a poor state
5. Automatic beats guide each time: we’re a busy group doing a variety of issues,
   it’s all the time going to be tough to persistently discover time to manually curate content material deeply,
   targeted curation is nice, however world is unreasonable

Implementation

Then the specifics of implementing that coverage have been:

1. Create Scheduled to Archive and Archive teamspaces.
   The Archive teamspace is a personal teamspace, such that paperwork added there don’t pollute the search index.
   Conversely, Scheduled to Archive is public, the place anybody can add paperwork to its root doc.

   We have a weekly script that migrates every part from Scheduled to Archive to Archive.

   This was the simplest mechanism we may discover to implement archiving inside Notion’s constraints.

2. Prune expired pages. Created a script which recursively builds hierarchy from a root web page,
   enriches every web page with the last_edited_date for every youngster, after which prunes all pages
   the place it and all kids have been final edited greater than N days in the past.

   Using this script on 3-4 most related top-level pages, we archived about 1,500 pages of expired documentation.

3. Compact stale hierarchies. Created a second script which identifies present pages deep in stale hierarchies,
   e.g. the one up to date web page amongst 15 inaccurate docs. After discovering a “buried present web page”, promotes it to the grandparent web page,
   and transfer the dad or mum web page (and its stale kids) to Scheduled to Archive.

   This ended up as a script that discovered all of the candidates, after which I labored by approving/rejecting
   every suggestion. The greatest subject being the shortage of “verification” standing throughout the API, such that there’s
   no solution to bless given pages and their descendants.

4. Stale hyperlink finder. Created a 3rd script which recursively works by a hierarchy and finds 404s.
   It’s important that this script doesn’t have entry to the Archive so these scripts present up as 404s,
   in any other case you would need to scan by Archived to seek out issues there. Both approaches would work,
   only a little bit of a matter of desire.

   Ran this after the mass migrations to make sure we didn’t depart a “haunted forest” of hyperlinks into
   archived paperwork that folk can’t see, which might make the documentation nonetheless really feel dangerous regardless that
   a lot of the dangerous content material was eliminated.

5. Manual evaluation of key pages. After operating all the above steps, I then labored by all
   new-hire documentation to make sure it was linked to top-level onboarding information, said clear stipulations,
   indicated the Slack channel to get assist if of us bumped into bother,
   and ensured that directions didn’t duplicate our Git-managed READMEs, as an alternative linking to them the place
   applicable.

   I did a lighter go of this strategy for our top-level engineering and know-how pages,
   though these have been usually in a very good place.

Altogether, I feel this was about eight hours of my time, however required zero hours of anybody
else’s, and can have hopefully considerably improved the standard of our documentation.
There’s nonetheless much more to be performed in particular areas, however I’m optimistic that having far fewer duplicates,
and extra proof that we’re actively sustaining the documentation, will make that simpler as effectively.