Docs Homepage and a Constrained IA Redesign

What problem existed?

A large developer-tools documentation site had grown over time, and every product area, guide, and reference page lived in one left navigation. As the docs grew, that tree grew deep. There was no top-level wayfinding and no homepage to orient a new reader; the entry page was the top of the nav.

Reaching a specific page meant working down the tree. The opportunity was to add orientation on top of everything already there: clear entry points and a shorter path in.

Why did it matter?

Docs are often the first and most-used surface of a developer product.

As a docs site grows, wayfinding carries more of the experience. Clear top-level entry points and a short path to any page let people see what exists and find what they need, which supports adoption and eases support load. At thousands of pages, that orientation matters even more.

What constraints existed?

• Keep every URL. The hard one. The docs were already huge and linked from the product, search engines, articles, and customer bookmarks. Moving or renaming URLs would break those links at a scale no one could manage. The architecture could change how it presented itself, not where any page lived.
• Work inside the existing docs platform. A standard documentation generator, with its current content and build.
• By hand. I did the audit and the reorganization manually, with no AI in the loop.
• Teamwork. The shape came out of collaboration and rounds of feedback, not a solo redesign.

What role did I play?

I owned the design. I led the information-architecture work and the homepage, and the structure came together through teamwork and feedback.

I inventoried the existing pages, found the natural groupings, designed the top-level categories and the per-section navigation, and shaped the homepage entry points.

What options were explored?

• Tidy the single tree. Keep one left nav, just cleaner. It does not remove the depth or add any orientation.
• Restructure the content and the URLs. The clean-slate option, and the one that breaks the constraint.
• A presentation layer over the same pages. Add top-level categories, a homepage with entry points, and a short nav per category, all mapped onto the existing URLs. This is what we built.

What tradeoffs were considered?

The main tradeoff was ideal structure against link stability. A from-scratch IA would have been cleaner, but the cost of broken links across a huge, widely-referenced site was not worth it. So the new architecture is a navigation model layered over the existing pages. The grouping and the path into a page changed; the page’s URL did not.

A second tradeoff was breadth against depth. Moving the categories into a top nav, and giving each its own short left nav, traded one very deep tree for a shallow, scoped one.

How did UX, engineering feasibility, and business strategy intersect?

The redesign was mostly a mapping problem. Every existing page kept its URL, and the new navigation, the top nav, the category landing pages, and the short scoped left navs, was a layer pointing at those unchanged pages.

That kept engineering effort low, with no content migration and no redirects to manage, while the experience changed substantially.

How was AI used in the process?

It was not. I did this one entirely by hand, and that is exactly what makes it useful here.

I audited the entire documentation tree by hand. I went page by page, catalogued what existed, and worked out the groupings myself. On a site this large, that inventory was the slow, heavy part of the work.

AI would help most with exactly this step. An agent could crawl the full URL tree, inventory every page, cluster pages by topic, and surface overlaps, orphans, and miscategorized pages far faster than I did by hand, then propose candidate groupings to react to. The design judgment, which entry points make sense, how the homepage should read, what a category means, would still be mine. The audit-and-cluster step is the kind of mechanical, large-scale analysis AI is good at, and doing it manually is what made this slow.

If I ran it again, the audit would start here:

Crawl the full documentation tree and inventory every page:
URL, title, and what it covers. Cluster the pages by topic,
and surface the overlaps, the orphans, and anything filed
under the wrong group. Propose a few candidate groupings for
me to react to. The call on entry points and category names
stays with me.

What was learned?

On a large site, the hard part of an IA redesign is the inventory and the clustering, not the visual design.

The URL constraint had a useful side effect: it forced a clean separation between the navigation model and the content structure, which is what let the architecture improve without anything moving. The next time I do this, the audit is the part I would hand to AI.

What was the outcome?

A documentation homepage with clear “browse by area” entry points, a top nav of real categories, and a short, scoped left nav per category with landing pages and breadcrumbs, all on the original URLs.

A reader can now see where they are and what exists, with a short path to any page. The navigation got shorter and clearer, and not one link broke.