[{"data":1,"prerenderedAt":247},["ShallowReactive",2],{"case-study:documenting-a-system-nobody-understood":3},{"id":4,"title":5,"body":6,"description":214,"draft":215,"extension":216,"industry":217,"meta":218,"metrics":219,"navigation":229,"order":230,"path":231,"role":232,"seo":233,"stack":234,"stem":240,"tags":241,"year":245,"__hash__":246},"caseStudies\u002Fcase-studies\u002Fdocumenting-a-system-nobody-understood.md","Documenting a system nobody fully understood",{"type":7,"value":8,"toc":199},"minimark",[9,14,18,22,25,33,36,40,43,48,56,124,130,134,137,141,148,152,155,159,165,171,177,181,187,193],[10,11,13],"h2",{"id":12},"in-one-line","In one line",[15,16,17],"p",{},"I turned a legacy platform that lived only in the heads of whoever had touched it\nlast into a 138-page reference that mapped every legacy action to its\nreplacement, so the migration was archaeology done once and written down, not\nre-discovered by every developer who touched a module.",[10,19,21],{"id":20},"the-problem","The problem",[15,23,24],{},"The legacy platform had effectively no documentation. What existed was a handful\nof stale wiki pages, scattered and contradictory, plus tribal knowledge that left\nthe building whenever someone did. The business logic for a single feature was\nroutinely spread across four codebases: a first-generation SOAP webservice, a\nsecond-generation JSON-RPC service, an aging frontend, and a separate UI app.",[15,26,27,28,32],{},"That is a bad place to start a migration from. Every module a developer picked up\nbegan the same way: hours of grep-driven archaeology across four repositories to\nanswer one question - ",[29,30,31],"em",{},"what does this actually do today, and where?"," The same\nexcavation happened again the next time someone touched an adjacent feature,\nbecause the answer was never written down.",[15,34,35],{},"The migration could not be estimated, sequenced, or parallelised while the ground\ntruth lived only in code nobody wanted to read.",[10,37,39],{"id":38},"what-i-built","What I built",[15,41,42],{},"A documentation portal (Nuxt Content \u002F Docus, Mermaid diagrams), sole author,\nthat grew to 138 pages across five sections: general reference and glossary,\nbackend, middleware, frontend, and the migration itself. It was not a wiki of\nprose. It was structured to answer the questions the migration actually asked.",[44,45,47],"h3",{"id":46},"_1-a-gap-analysis-that-mapped-the-whole-legacy-surface","1. A gap analysis that mapped the whole legacy surface",[15,49,50,51,55],{},"The centrepiece. A domain-by-domain comparison of legacy versus new, covering all\n14 feature domains, that quantified the entire legacy surface: roughly ",[52,53,54],"strong",{},"820\nlegacy actions",", against which the new stack's endpoints were tracked. For every\nfeature it recorded the exact legacy source and its new-stack replacement:",[57,58,59,75],"table",{},[60,61,62],"thead",{},[63,64,65,69,72],"tr",{},[66,67,68],"th",{},"Feature",[66,70,71],{},"Legacy source",[66,73,74],{},"New stack",[76,77,78,94,107],"tbody",{},[63,79,80,84,91],{},[81,82,83],"td",{},"Login \u002F logout",[81,85,86,87],{},"V2 ",[88,89,90],"code",{},"Auth\u002FAcl",[81,92,93],{},"Auth module, 11 endpoints",[63,95,96,99,104],{},[81,97,98],{},"MFA (TOTP, email OTP)",[81,100,86,101],{},[88,102,103],{},"Acl.activateMultiFactorAuthentication",[81,105,106],{},"dedicated endpoints",[63,108,109,112,121],{},[81,110,111],{},"Password reset",[81,113,86,114,117,118],{},[88,115,116],{},"Acl.forgotPassword"," \u002F ",[88,119,120],{},"resetPassword",[81,122,123],{},"3 endpoints",[15,125,126,127],{},"Multiply that across 14 domains and hundreds of actions. The result answered, on\none page, the question every developer had been re-deriving by hand: ",[29,128,129],{},"this is what\nexists, this is where it lives, this is what replaces it, and this is how much is\nleft.",[44,131,133],{"id":132},"_2-a-live-migration-tracker","2. A live migration tracker",[15,135,136],{},"Every feature across API, middleware and frontend, with a status legend\n(complete \u002F in progress \u002F documented \u002F not started \u002F partial \u002F skipped) so anyone\ncould see the true state of the migration without asking. Phases were planned\nagainst it; ownership was assigned against it.",[44,138,140],{"id":139},"_3-a-migration-document-per-module","3. A migration document per module",[15,142,143,144,147],{},"Each module got its own document written ",[29,145,146],{},"before"," implementation began: what was\nbeing extracted, from which legacy sources, into which new module boundary, with\nthe file-by-file breakdown of the new structure. The document was the plan and,\nafterwards, the record.",[44,149,151],{"id":150},"_4-the-reference-layer","4. The reference layer",[15,153,154],{},"A 70-entry glossary that pinned down the domain vocabulary (the same term meant\ndifferent things in different legacy apps), plus architecture, tooling and\nconvention pages, so a decision made once did not get relitigated in every review.",[10,156,158],{"id":157},"why-it-mattered","Why it mattered",[15,160,161,164],{},[52,162,163],{},"It changed the unit of migration work from \"excavate, then build\" to just\n\"build.\""," The most expensive part of each migration - reconstructing what the\nlegacy system did and where - was done once, by me, and written down. Every\nsubsequent developer, and every AI-assisted session, started from the map instead\nof the grep.",[15,166,167,170],{},[52,168,169],{},"It made the migration estimable and parallelisable."," You cannot sequence work\nyou cannot see. The gap analysis turned \"the legacy system is a black box\" into\n\"627 of 820 actions remain, here are the hard ones, here is the order\" - which is\nthe difference between a plan and a hope.",[15,172,173,176],{},[52,174,175],{},"It survived its author."," The whole point of writing down where every piece of\nlegacy logic lives is that the knowledge stops walking out of the door. The\nplatform went from \"ask the person who last touched it\" to \"read the docs\" for\nevery future hire.",[10,178,180],{"id":179},"what-i-would-tell-someone-starting-this","What I would tell someone starting this",[15,182,183,186],{},[52,184,185],{},"Document the questions, not the code."," Nobody reads a wiki that mirrors the\nsource. They read the one page that answers \"where does this live and what\nreplaces it,\" so build the reference around the decisions people actually make.",[15,188,189,192],{},[52,190,191],{},"The map is worth more than the territory when the territory is four codebases.","\nThe single highest-leverage artefact was not any module's documentation; it was\nthe one table that reconciled four legacy sources into one view. Build that first.",[15,194,195,198],{},[52,196,197],{},"Write the migration doc before the migration."," A plan written down is a plan\nthat can be reviewed, estimated, and handed off. Written afterwards, it is just a\nchangelog.",{"title":200,"searchDepth":201,"depth":201,"links":202},"",2,[203,204,205,212,213],{"id":12,"depth":201,"text":13},{"id":20,"depth":201,"text":21},{"id":38,"depth":201,"text":39,"children":206},[207,209,210,211],{"id":46,"depth":208,"text":47},3,{"id":132,"depth":208,"text":133},{"id":139,"depth":208,"text":140},{"id":150,"depth":208,"text":151},{"id":157,"depth":201,"text":158},{"id":179,"depth":201,"text":180},"A legacy platform with no documentation and business logic split across four codebases. I reverse-engineered it into a 138-page reference that mapped roughly 820 legacy actions to their replacements, so the migration ran against a map instead of guesswork.",false,"md","Payments \u002F Fintech",{},[220,223,226],{"value":221,"label":222},"138","pages, sole author, from scattered wiki notes",{"value":224,"label":225},"~820","legacy actions mapped to their replacements",{"value":227,"label":228},"4 → 1","source codebases reconciled into one reference",true,4,"\u002Fcase-studies\u002Fdocumenting-a-system-nobody-understood","Senior Full-Stack Developer",{"title":5,"description":214},[235,236,237,238,239],"Nuxt Content","Docus","Markdown","Mermaid","Information Architecture","case-studies\u002Fdocumenting-a-system-nobody-understood",[242,243,244,239],"Documentation","Migration","Developer Experience","2026","ZIhnag5mh_aav7AunRwNRiN5sOG2_IApd-IaeIGyxpg",1787792667591]