{"database": "pelican", "table": "content", "rows": [["ryan", "musings", "## The Roman Colosseum\n\nAfter the fall of the Western Roman Empire in 497 CE the Colosseum fell into\ndisrepair. Rightfully so! Who can worry about keeping up a giant megalith made\nby people centuries ago while you're just trying to figure out where your next\nmeal may come from, or the ranging hordes of barbarians showing up and taking\nthe food you did find!\n\nHowever, during the medieval period, while Rome's population declined\ndramatically and many ancient structures fell into disrepair or were\nrepurposed, the Colosseum remained a prominent landmark. There are stories\nthat as the centuries progressed, the inhabitants of Rome forgot who built it.\nWhile some fantastical legends did develop around it, the basic historical\nfacts of its construction by the Flavian emperors and its original purpose\nremained part of common knowledge among educated Romans. For the non-educated\nRoman's there were lots of misconceptions about the colosseum.\n\nThe non-education Romans would have created stories1 about the large building.\nIt was haunted. It was used for pagan rituals and no good Christian would go\nin. Folklore would rise up around it. As many of us have seen or experienced,\nin the absence of information, people will make it up.2\n\n## The Story of the Legacy System\n\nOK, but why is this important from a technology perspective?\n\nImagine if you will a large system, built 10 years ago, by a group of\ndevelopers, that have all left the organization.\n\nNo one left knows how it works, or how to make changes to it. Most people\ndon't even really know WHY it's there in the first place.\n\nThere isn't any documentation that can be referred to. Either because it\nwasn't ever created OR it was destroyed by Barbarians, I mean well meaning IT\nprocesses that 'clean up' unused files.\n\nSo what happens? The people remaining create stories about the system. Stories\nlike the long timer 'Bob' that once caused the entire system to Crash and then\nan old copy backup copy had to be restored, and months worth of work was lost.\n\nNo one ever saw Bob after that. Now we're all afraid to touch any part of it.\nWe mostly leave it alone, and it leaves us alone.\n\nThere are stories about another gray beard that actually built the system, but\neveryone assumes these are just fairy tales.\n\nThe stories tell of this Gray Beard busting out the entire system in a\nweekend, using nothing but a pin to move the electrons into the proper places\nto get all of the logic to work as expected.\n\nOf course, no one really believes that story, but it encourages people to\nnever want to have to make and changes to it.\n\nThe problem here is that it's running on a server with an OS that hasn't been\nsupported for 7 years and there is security mandate to upgrade 'everything' to\nbe on current software\n\nNo one wants to be in charge of this project, but someone is going to have to\nbe in charge of it.\n\nWhat do you do?\n\nThe story above isn't real, at least not for me. But it could be.\n\nHow many times have you gotten to a system that is old, no one around has any\nidea how it was built and people mostly just avoid it? Probably more than\nonce.\n\nBut how can we avoid this fate? Do we just keep the old timers on until they\n(or the system) die?\n\nThere are options, and they are some of the easiest things to do, but many\npeople don't like to do them.\n\nWhat is the answer?\n\n## Documentation\n\nDocumentation. No really, Documentation. Just write it down. For a new project\nespecially. For an old project? Most definitely.\n\nFor new projects it's best to just get into the habit of writing good docs3 as\nyou go. If that's doc strings in a method, or a full fledged Knowledge\nManagement System using a documentation framework like\n[diataxis](https://diataxis.fr/), then so be it.\n\nBut write it down. Write down the why's whenever you can. Use something like\nan [Architectural Decision\nDsocument](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-\ndecisions) to understand WHY you made a technical decision you made. Maybe\nit's not the best decision, but it's the best decision given a set of\nconstraints.\n\nFor existing projects, it can be more challenging. It's possible that NO ONE\nthat created the system is at the organization. It could be that NO ONE that\nasked for the system to be created is at the organization.\n\nThis leads to a bunch of problems to try to solve, but the journey of 1000\nmiles starts with a single step.\n\n## How do you solve it?\n\nUse the helpful [Awareness-Understanding\nMatrix](https://en.wikipedia.org/wiki/There_are_unknown_unknowns)4\n\n| Aware | Unaware  \n---|---|---  \nUnderstand | Known Knowns | Unknowns Known  \nDon't Understand | Known Unknowns | Unknown Unknowns  \n  \nThat is,\n\n  * Known Knowns: Things we are aware of and understand\n  * Known Unknowns: Things we are aware of but don't understand\n  * Unknown Knowns: Things we are not aware of but do understand or know implicitly\n  * Unknown Unknowns: Things we are neither aware of nor understand\n\nThe Known Knowns may be very small, but it won't be empty.\n\nThe Unknown Unknowns might (will probably) be the largest.\n\nThe lack of knowledge here represents Risk5. Risk to your team, or to your\norganization. This Risk needs to be handled as much as possible.\n\nLooking at a system with the Awareness-Understanding Matrix can help to risk\nit properly. Once you've properly risked the system, then you can start\nwriting documentation.\n\nThe documentation can take the form of Architectural Review of System X\n(DRAFT)\n\nThe system does these things\n\n  1. Thing 1\n  2. Thing 2\n  3. Many other things that are still unknown\n\nSometimes just the act of writing these things out will help you in finding\nout what you know and what you don't know.\n\nIf you're using a documentation framework like\n[diataxis](https://diataxis.fr/) for this, you will want to keep your\ndocumentation parts separated (How To, Tutorials, Reference, Explanation). You\nmay start righting a Reference article on the system and realize that you also\nneed to have some, yet to be discovered, Explanation. The issue is that the\nExplanation still needs to be researched and written.\n\nThat's OK! One strategy I've encouraged, and use, is if I'm writing a\nReference Article and need to link to a yet to be written Explanation article,\nis that I'll simply create the yet to be written Explanation article and tag\nit with `Explanation` and `Stub`. This frees me to come back to it later and\nfill in the details.\n\nThe other thing that will need to be done is to figure out who uses the\nsystem. Sometimes that's super easy, and sometimes, it's not.\n\nOnce you're able to determine who uses the system, you can talk with them\nabout the system and then work to fill in the gaps from above.\n\nOccasionally, you find out who everyone _thinks_ is using the system, and\ndiscover that actually, it hasn't been used for 5 years because **reasons** ,\nand they didn't know who to tell.\n\nNow you can just retire the system using a decommissioning process. You have a\ntechnology decommissioning process, right? If you don't, it may be time to\nlook into one!\n\n## Back to the colosseum\n\nThe inhabitants of Rome never got to a spot where none of them knew why it was\nbuilt, or who built it. Or even why. But what did happen is that the people\nwith the knowledge may have been parts of groups that were marginalized and\ntherefore their knowledge was discounted or ignored. Because the knowledge was\na verbal knowledge and not written down. It was, to use a loaded term, tribal\nknowledge. EVERYONE just knows the obvious thing.\n\nBut the thing is ... obvious things are only obvious in the context they were\ncreated. It's obvious what Python is. I mean, why would someone use a snake to\nwrite code to get a computer to do a thing. EVERYONE knows I'm talking about\nthe programming language Python ... until they don't.\n\nJust write this shit down. Make sure everyone gets into the habit of\ndocumenting. Make the documentation public. And if it's not possible to make\nall of the documentation public, make as much public as possible.\n\nFor the parts that aren't public, make sure they are accessible by the people\nthat will need access to it.\n\nReally, documentation is a means to an end. Sometimes you won't need the\ndocumentation. You'll know how the thing works, and it has an obvious API or\nUI and people just \"get it\". This can lead to people not writing the\ndocumentation because we don't need it.\n\nThis is kind of like saying, I've used a seatbelt every day for 30 years and\nI've never needed it. I don't see why I need to wear it any more.\n\nThis might be fine until you're in an accident.\n\nNot writing documentation is fine, until it's needed. And that's the worst\ntime to discover that you need it.\n\nBetter to have it and not need it, than to need it and not have it.\n\n  1. such as it being a temple to the sun \u21a9\ufe0e\n  2. Bren\u00e9 Brown \u21a9\ufe0e\n  3. any docs in this case are good docs! \u21a9\ufe0e\n  4. This is in no way an endoresement of Donald Rumsfeld. He was a horrible person \u21a9\ufe0e\n  5. Jacob Kaplan-Moss has a great series on [Risk](https://jacobian.org/series/risk/) \u21a9\ufe0e\n\n", "2025-01-21", "remember-the-colosseum", "## The Roman Colosseum\n\nAfter the fall of the Western Roman Empire in 497 CE the Colosseum fell into\ndisrepair. Rightfully so! Who can worry about keeping up a giant megalith made\nby people centuries ago while you're just trying to figure out where your next\nmeal may come from, or \u2026\n\n", "Remember the Colosseum!", "https://www.ryancheley.com/2025/01/21/remember-the-colosseum/"]], "columns": ["author", "category", "content", "published_date", "slug", "summary", "title", "url"], "primary_keys": ["slug"], "primary_key_values": ["remember-the-colosseum"], "units": {}, "query_ms": 0.6685648113489151}