Imagine this scenario, it’s well past midnight, and I just spent three hours debugging a complicated issue and finally was able to solve it. The rational part of my brain says “go to bed, you are too tired” but instead, I’m opening a md file to write down the analysis. Does it happen with you also? Then you are at the right place, read on.
Somewhere deep in my soul, I know that six months from now, I will need to add a new component to our design system, and future-me will have completely forgotten this edge case in our KMM shared layout engine.
Welcome to the mind of an IT professional, where documentation isn’t just a best practice—it’s a compulsion.
The Trauma That Started It All
Every one of us has that origin story. Mine was when our entire app went blank in production because someone changed a field name in the server response from “backgroundColour” to “backgroundColor”.
The only developer who knew about the British spelling convention in some of our legacy endpoints had left for a startup three months earlier. No documentation. No notes. Just a Slack thread buried in a deleted channel and sixteen hours of comparing server responses with client parsers.
We’ve all been there. Staring at undocumented JSON schemas, mysterious KMM expect/actual implementations, or a server-driven component that works in Compose but crashes in SwiftUI for “no apparent reason.”
That’s when the documentation obsession takes root. We swear a blood oath: “Never again will I let this happen to anyone else (especially future-me).”
The README That No One Reads
Here’s the thing we all know but don’t talk about: nobody reads our documentation. That beautifully crafted wiki explaining our server-driven UI architecture, complete with JSON schema examples and platform-specific rendering flows? It has ten views, and eight of them are from us, the team, checking if the sequence diagrams properly show the component lifecycle.
But we keep writing anyway. Why? Because documentation isn’t really for other people—it’s for us. It’s our external brain, our peace of mind, our insurance policy against our own forgetfulness. This is the only way we can go to sleep at the end of the day, and make space in our limited memory for newer things.
I once spent an entire weekend documenting our custom component protocol—how the server JSON maps to KMM models, how those models translate to Compose and SwiftUI views, and why we need seventeen different fields just to render a button. Did anyone ever read it? No. Did I read it six months later when we needed to add dark mode support to all components? You bet I did. And I silently thanked past-me for documenting every single field and its platform-specific quirks.
The Art of Writing for Your Future Self
We’ve developed a unique writing style. It’s not technical writing in the traditional sense—it’s more like leaving breadcrumbs for a very specific person: ourselves in six months, probably trying to add a new component type.
Our documentation includes gems like:
“DO NOT CHANGE THIS ENUM ORDER. The iOS app will crash. Yes, even though we use string keys. Don’t ask.”
“This @OptIn(ExperimentalMaterial3Api::class) is load-bearing. Future versions of Compose might fix this. They won’t.”
“If SwiftUI is showing a blank screen, check if the server is sending ‘alignment’: ‘middle’ instead of ‘center’. I know they mean the same thing. SwiftUI doesn’t.”
“The KMM data class MUST have default values for all fields. The server will randomly omit fields it considers ‘obvious’.”
We write with the assumption that future-us will have forgotten everything but will somehow be dealing with an even weirder platform-specific issue.
The Hidden Benefits Nobody Talks About
Here’s what people outside our world don’t understand: documentation is how we maintain sanity across many codebases (e.g. server, KMM, and platform-specific UI). Writing it down isn’t just recording information—it’s processing why Compose needs a Modifier.fillMaxWidth() while SwiftUI needs .frame(maxWidth: .infinity), and why our KMM abstraction pretends they’re the same thing.
I can’t count the number of times I’ve discovered inconsistencies in our component protocol while documenting a new feature. Like realizing our “spacing” field means padding in iOS but margin in Android, and nobody noticed because we’ve all been unconsciously compensating in our platform implementations.
Plus, there’s something deeply satisfying about a well-documented component library. It’s like looking at a perfectly typed JSON schema that actually matches what the server sends. Sure, you might not need to implement a custom carousel today, but knowing exactly which fields to expect brings a strange comfort.
The day we had to extend an OTP view to suit the credit card number view, we had to rely on the documents and it was a lifesaver that none expected it to be when we developed OTP flow months ago.
The Documentation Paradox
We live in a constant state of documentation paradox. We complain that the backend team doesn’t document their ever changing schemas well, while simultaneously knowing that nobody reads our extensive “How to Add a New Component Type” guide. We spend hours creating beautiful diagrams showing how server JSON flows through KMM to platform-specific views, knowing full well that next week’s “quick fix” will bypass half of that flow.
But here’s the secret: we don’t document because we think someone will read it. We document because NOT documenting feels wrong. It’s like pushing KMM code without testing it on both platforms. Sure, it’ll probably work, but that nagging feeling will haunt you through every stand-up.
The Evolution of Our Obsession
Our documentation has evolved beyond simple README files. We now have:
– JSON schemas with more comments than actual schema
– Postman collections that tell the entire story of our API evolution
– KMM expect/actual implementation tables that look like the Rosetta Stone
– That one Notion page titled “PLATFORM DIFFERENCES – SUPER IMPORTANT” that contains every SwiftUI vs Compose quirk we’ve discovered
– Slack threads to ourselves with crucial findings like “TextStyle.fontSize is SP in Android but POINTS in iOS”
We’ve turned documentation into an art form, complete with component playground apps, interactive Storybook instances, and enough JSON examples to fill a book.
The Real Reason We Can’t Stop
At the end of the day, our documentation obsession isn’t about best practices or professional development. It’s more about fear. Fear of forgetting why we map “flex” to Column in Compose but VStack in SwiftUI. Fear of being the person who didn’t document that the server’s “shadow” object has different field names for iOS and Android. Fear of becoming the very problem we swore to solve.
But it’s also about hope. Hope that somewhere, someday, someone (probably us) will need to understand why our Button component has 47 optional fields and find that one comment explaining the business logic.
Hope that my 2 AM documentation session will save someone from reimplementing platform-specific rendering logic that already exists in our KMM layer.
So we keep writing. We keep documenting. We keep leaving these digital breadcrumbs for our future selves and our colleagues. Because in a world of constantly evolving design systems, breaking platform updates, and server responses that change based on the phase of the moon, our documentation is the one constant we can control.
And honestly? That component specification might gather dust, but the day someone actually needs it and finds it—complete with examples of edge cases in both Compose and SwiftUI—that’s better than any successful production deployment you’ll ever have.
