Propose a strategy to migrate fragmented docs into a unified docs-as-code system
Phased migration from fragmented docs to a unified Git workflow.
Inventory sources; choose SSG by team fit; automate extraction; phased rollout with redirects.
Big-bang cutover without audit, buy-in, or rollback.
What's really being asked
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.
The full answer
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.
The mistakes people make
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.
What usually comes next
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?
A 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.
Interview question
When migrating hundreds of pages from fragmented sources into a docs-as-code system, which approach best reduces risk and preserves SEO?
- a.Immediately script extraction of all pages into Markdown without auditing freshness, choose the SSG with the most GitHub stars, and cut over in a single batch.
- b.Inventory sources for freshness and ownership, pick an SSG aligned with team skills, automate conversion, migrate by domain with redirects, and establish CODEOWNERS.Correct
- c.Select an SSG based primarily on its default theme, assign engineers to migrate everything in one weekend, and ask users to update their bookmarks.
- d.Export all pages regardless of freshness into a single Git repository, choose an SSG the documentation team likes, and replace all legacy URLs with a single redirect to the new homepage.
Why? this is the answer
The correct strategy inventories content first, matches the SSG to team skills, automates conversion, rolls out gradually with page-level redirects, and enforces governance via CODEOWNERS. Distractor D is tempting because automation and popularity feel like safe engineering defaults, but skipping the freshness audit and performing a big-bang cutover risks migrating stale content and breaking inbound links.
Just read this? Test yourself on what you have been reading.
Read the original → dev.to
- #documentation
- #docs-as-code
- #migration
- #static-site-generators
- #interview-prep
You just looked this up. Could you explain it out loud?
That is the part interviews actually test. Tezvyn takes questions like this one and gives you what the interviewer is really checking, the answer that lands, and the mistake that ends the conversation, in the four minutes before your next meeting.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on documentation — each one lists the topics its interview covers.
See open roles