Rescuing a Legacy Docs Platform

Open-Source Software Foundation

CHALLENGE

One of the most widely used open-source software collections, with 100+ libraries, millions of downloads, and a global developer base, needed a new website. But decades of inconsistent formats, partial rewrites, and distributed contributor practices made trusted, searchable documentation difficult to deliver.

Three issues stood in the way:

Version Drift: Users could move between pages and unknowingly land on outdated documentation, breaking navigation and trust.
Inconsistent Documentation Formats: Maintainers had built docs independently for years, using different tools and conventions. The site needed to feel cohesive without changing how contributors worked.
Hard-to-Trace Infrastructure: Caching had spread across multiple layers, making failures slow to diagnose and harder to resolve.

The launch wasn't blocked by a single issue. It was blocked by accumulated complexity across content, infrastructure, and contributor workflows. Solving it meant modernizing the platform without disrupting the community that relied on it.

Implementation Details

The goal was to stabilize the documentation system, reduce architectural friction, and clear the path to launch without a broad rewrite.

Version Logic Made Consistent

Library version and navigation logic had accumulated across cookies, URLs, and server-side session state. With no single source of truth, version selectors, category filters, and library pages drifted out of sync. Users could select one release, click through the site, and unknowingly land on another.

Working hand-in-hand with the client team, Six Feet Up engineers traced how version, library, and category state moved through the site and found several overlapping systems managing the same behavior in conflicting ways.

The fix was architectural: a shared Django mixin that defined how the current version is inferred, stored, and reused across the site.

The benefits showed up quickly:

Pages were refactored to use a shared mixin, eliminating contradictory code branching and localized hacks.
Navigation became predictable across the site.
Redundant logic was removed, cutting load times on affected pages roughly in half.

Version drift stopped being something the team had to work around. The behavior became known, consistent, and predictable.

Documentation Normalized

Years of independent contributor workflows meant the documentation carried a mix of tools, formats, and layout preferences. The goal was never to standardize how maintainers wrote their docs, but to make the output look cohesive under the new site's shared visual styling.

Path-based styling proved unreliable because shared directories, unversioned docs, and legacy storage patterns made filesystem detection brittle. Reorganizing the structure was not an option because developers relied on downloading raw HTML locally.

Instead, the team parsed HTML with BeautifulSoup and inferred doc type from structural signatures. That allowed stronger styling where safe and lighter styling for legacy or customized docs, without disrupting maintainer workflows.

Changes were validated across four doc types, multiple browsers, responsive breakpoints, and both light and dark modes.

Infrastructure You Can Reason About

Caching and runtime behavior had become hard to debug, so the team simplified the architecture.

Cache layers were reduced to two tiers: Django and PostgreSQL for dynamic behavior, and Fastly for short-lived static and semi-static content. Redis was removed from critical paths because PostgreSQL was fast enough and less expensive. S3 remained the backing store, while low-traffic pages regenerated on demand.

The same simplification improved operations. The release reporting pipeline was refactored into parallel tasks with better observability and error handling. A Nix-based dev environment reduced onboarding friction, and sanitized production-like data made local development easier without pulling the full documentation archive.

RESULTS

The new site launched. Version drift stopped recurring, the release reporting pipeline became a normal part of the release cycle, and shared styling held up across formats without changing community workflows.

Through daily collaboration with the client, Six Feet Up helped stabilize a system carrying decades of accumulated knowledge and created a stronger foundation for future AI integration.

The team learned:

Centralize shared logic before adding features. Version handling became manageable once it lived in one place, removing an entire class of bugs and improving performance.
Let the content shape the architecture. Detecting document types by structure, not location, created consistency without forcing a clean-slate model.

Sometimes the best architectural decision is knowing what not to change.

Need to evolve a legacy system without disrupting the workflows around it? Let’s talk.