— Documentation: Foundations & Next Steps On Content Strategy

TLDR:

1. Fixing the foundation
   1. Port the existing documentation to Next.js using the AriaDocs template for a fast UI/UX modernization.
   2. Implement robust absolute routing, automated redirects, and dynamic internal linking to improve the author experience and SEO, leveraging next.config.js.
2. After we’ve fixed the foundation, long term we need to start thinking about content strategy & best practices to implement going forward from resources like
   1. Diataxis (Used by Github)
   2. Google’s Documentation Style Guide
   3. *Doc For Developers* by Jared Bhatti, Sarah Corleissen, Jen Lambourne, David Nuñez, Heidi Waterhouse (which I will finish reading in a few weeks)

Fixing The Foundation

The documentation looks dated, and the navigation is confusing. We’re long overdue for an overhaul, but we’ve been putting it off for years because it’s prohibitively time-consuming due to hardcoded links and serious SEO concerns. We need to fix this before moving forward.

Proposed Solution

We will use an off-the-shelf Next.js template—similar to the Next.js documentation itself—called AriaDocs for a drag-and-drop facelift with a modern suite of features developers have come to expect.

We will build a custom, automated system to handle routing, redirects, and internal linking. This system will be built around a build-time script that ensures all content URLs are permanent, all legacy paths are correctly redirected, and all internal links are unbreakable, all leveraging next.config.js.

1. Absolute Routing

Goal: All content will be served from clean, permanent, and SEO-friendly absolute URLs.

Mechanism: Every MDX file will define its public URL via a frontmatter property.

--

id: 'a2b4c6d8-e1f3-4a5b-9c8d-7e6f5a4b3c2d'

title: 'My Awesome Post'

seoPath: '/guides/my-awesome-post'

--

Content goes here...

The build script will use these seoPath values to generate rewrite rules in next.config.js, mapping the public URL to the underlying Next.js page structure.

Edge Cases: The build script will enforce the following rules: