Propose a strategy to migrate fragmented docs into a unified docs-as-code system

WHAT THIS TESTS: This question evaluates whether you can design a systems-level content migration that balances technical execution with organizational change management. Interviewers want to see that you treat documentation as a product surface, not an afterthought. They are looking for familiarity with static site generators, Git workflows, content normalization, and risk mitigation during platform transitions. The best answers demonstrate awareness of stakeholder alignment, developer experience, and the operational realities of maintaining redirects and avoiding link rot.

A GOOD ANSWER COVERS: First, discovery and inventory. You should propose crawling or exporting all three sources to build a content matrix that tracks ownership, last-updated dates, page traffic, and content type. This prevents carrying dead weight into the new system. Second, platform selection. Mention matching the SSG to team skills, such as Docusaurus or Astro Starlight for JavaScript-heavy teams, or MkDocs for Python-oriented groups, and emphasize Git-based version control as the source of truth. Third, extraction and normalization. Describe automated scripts to convert HTML and Wiki markup into clean Markdown, handling relative links, image assets, and frontmatter metadata. Fourth, phased rollout. Recommend migrating one product domain at a time, running parallel systems temporarily, and using HTTP redirects or proxy rules to preserve SEO and inbound links. Fifth, governance. Define CODEOWNERS, review workflows, and deprecation timelines so the new system does not drift back into fragmentation.

COMMON WRONG ANSWERS: A big-bang migration plan that ignores content freshness and duplicates outdated material. Choosing a platform based only on aesthetics rather than team skill fit and CI integration. Neglecting redirect strategy, which breaks external bookmarks and search rankings. Failing to address binary assets like images or diagrams that may be scattered across the legacy CMS. Proposing manual copy-paste for hundreds of pages instead of automated extraction. Forgetting to include technical writers and developer advocates in the migration plan, treating it as purely an engineering task.

LIKELY FOLLOW-UPS: How would you handle versioned documentation for multiple product releases? What is your strategy for preserving SEO rankings and handling broken links? How do you onboard non-technical contributors who are uncomfortable with Git? What automation would you put in place to prevent the new docs from becoming stale? How would you measure the success of this migration?

ONE CONCRETE EXAMPLE: Suppose the legacy CMS holds two hundred pages of API guides, the GitHub Wiki contains fifty troubleshooting articles, and twelve repos each have their own README and contribution guides. Your inventory reveals that forty percent of CMS pages have not been updated in eighteen months. You select Docusaurus because the frontend team already knows React. You write a Python script using BeautifulSoup to scrape the CMS export into Markdown with frontmatter, and you use a GitHub Action to sync Wiki changes into a staging branch during the transition. You migrate the API guides first because they have high traffic, setting up nginx redirects from the old CMS URLs. You sunset the Wiki two quarters later after confirming via analytics that redirect traffic has dropped below five percent of total docs visits.

Source: DEV Community