Documentation architect and founder of voix. Writes about migrating product documentation off proprietary platforms onto stacks teams own.
View all authorsDocs as code is a shipping model, not a shopping list. Copying another company's toolchain gives you their cost structure without their constraints, and most of the cost lands on the person maintaining the pipeline rather than the person writing the page. This is which parts pay for themselves, what has to be true before each one does, and what is theatre.
Content conversion is the visible part of a migration and the part that rarely fails. The part that fails is the URL layer: every bookmark, support macro, in-product help button, partner page and search result that points at the old docs. A redirect map keeps those working, and it is usually built last, in a hurry, by whoever is still awake.
Every migration proposal contains the phrase "content audit", and almost nobody says what comes out of one. It is not a reading exercise, and it is not a quality score out of ten. It is a classification pass that ends with one decision per page, a count next to each decision, and a named person who agreed to it.