Consolidating and Redesigning a Documentation Platform

Overview

A company-wide rebrand required us to retire an existing developer portal and move its content into the main documentation platform. The challenge was larger than migration. The existing documentation site already had navigation and discoverability problems, legacy content had unclear ownership, and existing links and bookmarks needed to continue working after launch. I led the documentation workstream from planning through launch. I redesigned the site’s information architecture and table of contents, planned and executed the content migration, created wireframes, built the updated experience in MadCap Flare and Bootstrap, integrated search, and coordinated testing and redirects. The result was one consolidated documentation platform with clearer navigation, updated content structure and terminology, improved search, and preserved access to legacy URLs.

My role

I led the documentation portion of the broader rebrand from planning through launch.

• Led. Coordinated the documentation work across Marketing, external consultants, internal stakeholders, and documentation peers.
• Architected. Redesigned the information architecture and table of contents for the documentation platform.
• Audited. Inventoried content from the retiring developer portal and mapped each item to its new destination.
• Governed. Required migrated content to have a clear owner and used the migration to identify content that should be updated, consolidated, or retired.
• Designed. Created sketches and wireframes before moving into implementation.
• Built. Implemented the redesigned documentation experience in MadCap Flare and Bootstrap.
• Migrated. Moved and updated content while applying new product terminology and brand requirements.
• Validated. Tested redirects, browsers, navigation, search, and core user journeys before launch.

Worked with

• Marketing. Led the overall company rebrand and coordinated brand and web requirements.
• External consultants. Supported content, UI design, and software integration.
• Internal stakeholders. Owned content and web properties affected by the migration.
• Documentation peers. Reviewed content and tested the redesigned experience against defined tasks.

The challenge

The company was changing its brand while retiring a separate developer portal.

Content from that portal needed to move into the main documentation platform, but the migration exposed several underlying problems: the documentation site’s navigation was already a known pain point, legacy content had inconsistent or unclear ownership, product names and terminology were changing, the two sites used different structures, and existing URLs, bookmarks, and search results needed to continue working after launch.

Simply moving the content would have preserved many of the same problems.

The project therefore became both a content consolidation effort and a redesign of the documentation platform.

Key decisions

1. Use the migration as a content audit. There was no reliable automated migration path from the existing WordPress content into the documentation platform. Rather than treating the manual migration purely as overhead, I used it as an opportunity to review each item before it moved. Content could be retained, rewritten, consolidated, or retired instead of automatically carrying legacy problems into the new platform. Trade-off: Manual migration took longer, but it improved the quality of the resulting content set.
2. Require clear ownership before migration. Legacy content without an identifiable owner created a long-term maintenance risk. I worked with stakeholders to establish ownership before content moved into the redesigned platform. Content that nobody could support became a candidate for retirement. Trade-off: This created additional work during migration, but reduced the amount of orphaned content carried forward.
3. Design the information architecture before building. I began with sketches and then created Balsamiq wireframes for review before implementing the site. This allowed the team to evaluate navigation, hierarchy, and homepage concepts before development work became expensive to change. Trade-off: The design still evolved as new constraints and usability issues emerged.
4. Fix navigation as part of the consolidation. The existing experience relied on a long drop-down navigation and a side menu that moved with the page. The redesign introduced persistent side navigation and clearer high-level content groupings. Trade-off: The new experience required additional layout and styling work in the documentation platform.
5. Preserve old URLs. Moving content without redirect planning would have broken bookmarks, external links, search results, and references elsewhere on the web. I maintained an old-to-new URL map and tested the redirects before launch. Trade-off: Redirect mapping added significant validation work, but protected existing paths into the documentation.

My approach

I treated the project as a content and platform transformation, not just a visual redesign.

1. Plan. Set the goals, stakeholders, roles, milestones, and affected web properties.
2. Audit. Inventory existing content and identify ownership.
3. Map. Match old content and URLs to the new information architecture.
4. Design. Shape the navigation, homepage, and content hierarchy.
5. Migrate. Move and improve content as it transfers.
6. Build. Create the redesigned experience in the documentation platform.
7. Validate. Test navigation, browsers, search, redirects, and core tasks.
8. Launch. Release the consolidated documentation platform alongside the company rebrand.

The solution

The redesigned platform brought the retiring developer content and existing product documentation into one experience.

New information architecture: I reorganized the documentation structure and table of contents so related content was easier to find and navigate.

Redesigned homepage: the new homepage surfaced setup guidance, popular topics, and key content areas using a card-based layout.

Persistent navigation: a fixed side navigation replaced the previous experience and gave readers a more stable sense of location within the documentation hierarchy.

Improved search: I integrated Algolia DocSearch into the Flare-based site to improve content discovery.

Content consolidation: developer portal content was reviewed, updated, reorganized, and migrated into the primary documentation platform.

Redirect strategy: each legacy URL was mapped to its new destination, then redirects were tested before launch to preserve existing entry points.

Tools: MadCap Flare · Bootstrap · Balsamiq · Algolia DocSearch · BrowserStack

Impact

• One documentation platform: The retiring developer portal was consolidated into the main documentation experience instead of leaving users to navigate two separate sites.
• Redesigned information architecture: The platform received a new content structure and table of contents rather than simply applying new branding to the existing hierarchy.
• Improved navigation and discovery: Readers gained persistent side navigation, a redesigned homepage, clearer high-level content groupings, and integrated search.
• Reduced legacy-content risk: The migration forced unclear ownership to be resolved and created an opportunity to update, consolidate, or retire older content.
• Preserved existing access: Legacy URLs were mapped, redirected, and tested before launch, protecting bookmarks, search results, and existing links.
• Delivered with the rebrand: The redesigned documentation platform launched as part of the broader company rebrand and received positive customer feedback.

What I learned

Migration is an opportunity to improve the system. The most valuable part of the project was not moving content from one platform to another. The migration created an opportunity to examine ownership, structure, terminology, navigation, and content quality together instead of carrying the existing problems into a new environment.

The content map is as important as the visual design. The inventory and old-to-new content map became some of the most important project artifacts. They connected content decisions, information architecture, ownership, migration status, and redirect planning in one place.

URL continuity is part of the user experience. A redesign can look successful while still creating a poor experience if old bookmarks and search links stop working. Mapping and testing redirects made continuity a deliberate part of the launch rather than a cleanup task afterward.

Review design early and often. The design changed several times because of new constraints, usability findings, and broader company decisions. If I were running the project again, I would create more frequent design checkpoints before implementation and keep the development branch synchronized more aggressively to reduce rework and difficult merges.