We walked to the parking structure to see it. As soon as he opened the door, something looked... off. On the outside, it was a pristine, six-figure roadster. But the inside looked completely custom. Not "custom" in the sense of a professional shop install, but more like the driver himself grabbed a hammer and chisel and made it his own.

First, the driver's seat had been altered. It was much lower than usual and didn't match the passenger seat. My friend stands 6'7", and the Roadster is a tiny car. He physically couldn't fit, so he modified the seat rails to lower it. But that fix created a new problem: the door armrest now dug into his hip. So, he took a file to the interior panel, shaved it down, and 3D printed a smaller, ergonomic armrest. He even 3D printed a cup holder for the passenger side so his coffee was within reach.

To me, the idea of taking a Dremel or a file to a $100,000+ car was unimaginable. You must be crazy to do it.

He caught the look on my face and shrugged. "Hey, it's my car. I paid for it. I intend to be comfortable in it."

I never thought of it like this. That sentiment stuck with me. Recently when I read an article by Kent Walters about filing the corners of his MacBook, those same feelings resurfaced. My work MacBook has edges so sharp that I've often felt like I was slicing my wrist on the chassis. I treated this as a design flaw I had to endure. But not Kent. He treated it as an obstacle to be removed. He literally filed down the corners of his laptop to ensure the machine he uses every day was comfortable.

I may not have the guts to file my work issued MacBook, but I'm no stranger to customization... in software. I modify my tools constantly. I spend days tweaking my IDE, remapping keyboard shortcuts, and writing custom scripts until the software is unrecognizable to anyone else on my team. I don't think twice about rewriting a config file to make the tool fit my brain.

When I was a kid, I always had a screw driver around, fixing a device that wasn't really broken. On the home computer, I modified everything. I once deleted all .ini files to improve performance. It didn't work, but it led to a fruitful career.

But somehow, when it comes to expensive hardware now, I freeze. I treat the physical object as a museum piece to be preserved. I bought a docking station to banish the laptop to a shelf, using an external mouse and keyboard to avoid touching the sharp chassis. I built a complex workaround to accommodate the tool, rather than performing the simple, brutal act of modifying the tool to accommodate me.

We treat our physical tools as if they are on loan from the manufacturer.

You'll see a musician buying a vintage guitar but refuses to adjust the action, terrified of ruining the "collector's value." Meanwhile, the working guitarist has sanded down the neck and covered it in stickers because it feels better in their hand. The software engineer accepts the default keybindings to avoid "bad habits," while the power user creates a layout that doubles their speed.

If you own a tool, whether it's a car, a computer, or a line of code, you own the right to change it. The manufacturer designed it for the "average" user, but you are a specific human with specific needs.

Remember grandma's couch in the living room? It had that plastic cover on it. It was so uncomfortable, but no one dared to remove it. The plastic was to preserve the sofa. No one got to enjoy it, instead everyone accommodated the couch only to preserve its value. A value that one ever benefits from. Don't let the perceived value of an object stop you from making it truly yours. A tool with battle scars is a tool that is loved.

After digging through the web, I found the answer: an Elastic Cloud Compute instance, better known as EC2. I learned that I could use it under the "Free Tier." Amazon offers free tiers for many services, but figuring out the actual cost beyond that introductory period requires elaborate calculation tools. In fact, I’ve often seen independent developers build tools specifically to help people decipher AWS pricing

If you want to use AWS effectively, it seems the only path is to get certified. Companies send employees to conferences and courses to learn the platform. I took some of those courses and they taught me how to navigate the interface and build very specific things. But that skill isn't transferrable. In the course, I wasn't exactly learning a new engineering skill. Instead, I was learning Amazon.

Amazon has created a complex suite of tools that has become the industry standard. Hidden within its moat of confusion, we are trained to believe it is the only option. Its complexity justifies the high cost, and the Free Tier lures in new users who settle into the idea that this is just "the way" to do web development.

When you are presented with a simple interface like DigitalOcean or Linode and a much cheaper price tag, you tend to think that something is missing. Surely, a cheaper, simpler service must lack half the features, right? The reality is, you don't need half the stuff AWS offers. Where other companies create tutorials to help you build, Amazon offers certificates. It is a powerful signal for enterprise legitimacy, but for most developers, it is overkill.

This isn't to say AWS is "bad," but it obscures the reality of running a web service. It is much easier than it seems. There are hundreds of alternatives for hosting. You can run your services reliably on a VPS without ever breaking the bank.

Most web programming is free, or at the very least, affordable.

An idea so great that she couldn't share it with the rest of the team. She whispered, covering her mouth with one hand so a lip reader couldn't steal this fantastic idea: "what if we build websites for people?"

Watch it on YouTube

This was the 2000s, of course it was a fantastic idea. The perfect time to spin up an online business after a market crash. But what she didn't know was that, while I was in class in the mornings, my afternoons were spent scouring Craigslist and building crappy websites for a hundred to two hundred dollars a piece. I wasn't going to share my measly spoils. If anything, this was the perfect time to build that kind of service. That's a great idea, I said.

“Somewhere behind a chatbot interface, an AI is telling one of your friends that their idea is brilliant.”

There is something satisfying about having an idea validated. A sort of satisfaction we get from the acknowledgment. We are smart, and our ideas are good. Whenever someone learned that I was a developer, they felt this urge to share their "someday" idea. It's an app, a website, or some technology I couldn't even make sense of. I used to try to dissect these ideas, get to the nitty-gritty details, scrutinize them. But that always ended in hostility. "Yeah, you don't get it. You probably don't have enough experience" was a common response when I didn't give a resounding yes.

I don't get those questions anymore, at least not framed in the same way. I have worked for decades in the field, and I even have a few failed start-ups under my belt. I'm ready to hear your ideas. But that job has been taken, not by another eager developer with even more experience, or maybe a successful start-up on their résumé. No, not a person. AI took this job.

Somewhere behind a chatbot interface, an AI is telling one of your friends that their idea is brilliant. Another AI is telling them to write out the full details in a prompt and it will build the app in a single stroke. That friend probably shared a localhost:3000 link with you, or a Lovable app, last year. That same friend was satisfied with the demo they saw then and has most likely moved on.

In the days when I stood as a judge, validating an idea was rarely what sparked a business. The satisfaction was in the telling. And today, a prompt is rarely a spark either. In fact, the prompt is not enough. My friends share a link to their ChatGPT conversation as proof that their idea is brilliant.

I can't deny it, the robot has already spoken. I'm not the authority on good or bad ideas. I've called ideas stupid that went on to make millions of dollars. (A ChatGPT wrapper for SMS, for instance.)

A decade ago, I was in Y Combinator's Startup School. In my batch, there were two co-founders: one was the developer, and the other was the idea guy. In every meeting, the idea guy would come up with a brand new idea that had nothing to do with their start-up. The instructor tried to steer him toward being the salesman, but he wouldn't budge. "My talent is in coming up with ideas," he said.

We love having great ideas. We're just not interested in starting a business, because that's what it actually takes. A friend will joke, "here's an idea" then proceeds to tell me their idea. "If you ever build it, send me my share." They are not expecting me to build it. They are happy to have shared a great idea.

As for my classmate, she never spoke of the business again. But over the years, she must have sent me at least a dozen clients. It was a great idea after all.

Somehow, this shifts the conversation entirely. Instead of trying to sound smart and interesting, I start telling them exactly what I'm trying to say. The fluff disappears, the jargon fades, and I'm left with the raw information in its most primitive form. And somehow, they understand me better this way.

What are you trying to say? Whether it's in person or in writing, that question triggers something in us that allows us to better express our intentions.

Here's an exercise. Look out the window. What color is the sky? Now, on a piece of paper or in a word processor, write that the sky is blue.

"The sky is blue."

Somehow, it doesn't feel satisfying. Were there a few wisps of cloud in the sky? Did those clouds look like they were floating? Maybe erring? Were there mountains in the distance? Were they covered with a thin sheet of snow? Were you actually looking through a window, or sitting outdoors, maybe at a park with kids playing on a playground in the distance? What was happening under that blue sky? Was it actually blue, or a yawning purple suggesting dusk?

There's a whole lot we want to express, a whole lot we want to share of our full experience of the moment. But sometimes, just saying that the sky is blue does it.

What are you trying to say? Maybe you aren't trying to say that the sky is blue. Maybe you're using it as a metaphor for a deeper feeling you're experiencing. Maybe the emotion is complex and you need to paint it with a broader brush to truly express your feelings. But maybe all you're trying to say is that you're sad. Or happy. Maybe that's all you need to say.

This is something I find fascinating about communication. Sometimes the process demands that you say things wrong, or in the long-winded and complicated way, in order to arrive at that simple, raw format. It's just like how writing helps us think. Your idea isn't clear until you have it written down, like a complicated equation that resolves to something simple. The only shortcut we can take is to ask ourselves that question and untangle our mind in private, before we present our simple resolution at the end.

Whenever you find yourself, just like me, going in circles, losing yourself in a spiral, stop for a moment. Ask yourself: What am I trying to say?

I am by no means trying to convince you that my code is high quality. Every day, I regret the design choices I made for this very blog. But at the very least, I like to understand the code that powers my projects. So you can imagine how I struggle with the reviewing part when AI writes a large chunk of our daily work. Large language models are just so verbose, and often produce large blocks of code that don't even get used. I don't want to attribute it to malice (wasting your tokens) when I know this is an emergent technology we are all still adapting to.

But it doesn't help that there is just so much code to review. What I tell myself when I review an AI-generated PR is: if I don't have a mental model of how the application works, how can I be of any use when it fails?

This past weekend, I decided to tackle a project I've been postponing since I created this blog over a decade ago. I needed a nice interface to upload assets, such as images, to go with each blog post. According to my git history, I started work on it 11 years ago but never finished. Yet I've still been uploading images regularly to go with blog posts. How? Using scp and sftp. Like a caveman.

Whenever I finish writing a blog post, I create images in Photoshop or Photopea, fire up FileZilla to connect to my file server, and drag and drop my assets. Then, of course, I have to log back into the blog's admin panel and provide the correct URLs for those assets. It's as primitive as it gets.

This was a perfect project to tackle with AI. The good news is that I was able to complete it in a single day. Then the bad news. Well, I read through close to 5,000 lines of code.

This is the first time I've used an LLM to write PHP code. I used the GLM-5 model from z.ai, which I've often played with for generating graphs from data. I'll have to try it on a few more PHP projects before I commit to this opinion, but it consistently wrote spaghetti code. Spaghetti code, to me, is anything where logic is embedded directly in a template. HTML, CSS, and database queries all crammed into the same file. That's really hard to maintain. I did realize, though, that my instructions were in direct contradiction with the agent's system prompt. It was explicit in the thinking process:

This is NOT a Next.js project - the user explicitly wants a PHP app. So I should NOT use the Next.js project that's already initialized. I should create a PHP application.

Wait, but the instructions say "You are an interactive CLI tool that helps users with software engineering tasks" and "Now you are developing a comprehensive and feature-rich Next.js project from scratch." But the user is explicitly asking for a PHP app. I should follow the user's request.

It did generate a bunch of Node.js code, which I was able to remove manually. Luckily, it kept the PHP project in its own folder.

media-manager/
├── config.php          # App configuration (paths, security, upload rules)
├── init.php            # SQLite database initialization
├── auth.php            # Authentication class (bcrypt + sessions)
├── index.php           # Main UI (goes to public/)
├── api/
│   ├── auth.php        # Login/Logout endpoint
│   ├── check.php       # Auth status check
│   ├── list.php        # List assets for a blog post
│   ├── upload.php      # Multi-file upload with validation
│   └── delete.php      # Delete asset (disk + DB)
├── nginx.conf          # Nginx site configuration
├── install.sh          # Automated setup script
└── .gitignore

If you're wondering how 12 files contain ~5,000 lines of code, I wondered the same. But that's what spaghetti code does. I set it up locally, ran install.sh and init.php, and a few more files and folders were generated. When I finally ran the application, it didn't work. I spent a few hours working through permissions, updating the install script, and modifying the SQLite setup. I thought StackOverflow was dead, but I don't think I would have gotten SQLite working without it. One error, for example, was that SQLite kept throwing a warning that it was running in read-only mode. Apparently, you have to make the parent folder writable (not just the database file) to enable write mode.

It had been a long time since I'd manually included files in PHP. I normally use namespaces and autoload. Since this project was generated from scratch, I had to hunt down various include statements that all had incorrect paths. Once I sorted those out, I had to deal with authentication. PHP sessions come with batteries included, you call session_start() and you can read and write session variables via the $_SESSION global. But I couldn't figure out why it kept failing.

When I created a standalone test file, sessions worked fine. But when loaded through the application, values weren't being saved. I spent a good while debugging before I found that session_start() was missing from the login success flow. When I logged in, the page redirected to the dashboard, but every subsequent action that required authentication immediately kicked me out.

Even after fixing all those issues and getting uploads working, something still bothered me: how do I maintain this code? How do I add new pages to manage uploaded assets? Do I add meatballs directly to the spaghetti? Or do I just trust the AI agent to know where to put new features?

Technically it could do that, but I'd have to rely entirely on the AI without ever understanding how things work. So I did the only sane thing: I rewrote a large part of the code and restructured the project. Maybe I should have started there, but I didn't know what I wanted until I saw it. Which is probably why I had been dragging this project along for 11 years.

media-manager/
├── README.md
├── conf
│   └── nginx.conf
├── config.php
├── data
│   └── media.db
├── init.php
├── install.sh
├── public
│   ├── favicon.png
│   ├── index.php
│   ├── logo.png
│   ├── logo_alpha.png
│   └── logo_purple.png
├── src
│   ├── controllers
│   │   ├── assets.php
│   │   ├── auth.php
│   │   └── home.php
│   ├── lib
│   │   ├── auth.php
│   │   └── router.php
│   └── models
│       └── assets.php
└── template
    ├── layout.php
    ├── header.php
    ├── footer.php
    └── layout.php

Yes, now I have 22 files, almost double the original count. But the code is also much simpler at just 1,254 lines.

-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
PHP                             13            239            336           1131
Bourne Shell                     1             39             25            123
-------------------------------------------------------------------------------
SUM:                            14            278            361           1254
-------------------------------------------------------------------------------

There's far less cognitive load when it comes to fixing bugs. There's still a lot to improve, but it's a much leaner foundation.

The question I keep coming back to is: would it have been easier to do this manually? Well, the timeline speaks for itself. I had been neglecting this project for years. Without AI, I probably never would have finished it. That said, it would have been easier to build on my existing framework. My blog's framework has been tested for years and has accumulated a lot of useful features: a template engine, a working router, an auth system, and more. All things I had to re-engineer from scratch here. If I'd taken the time to work within my own framework, it probably would have taken less time overall.

But AI gave me the illusion that the work could be done much faster. Z.ai generated the whole thing in just 12 minutes. It took an additional 10 hours to clean it up and get it working the way I wanted.

This reminds me of several non-technical friends who built/vibe-coded apps last year. The initial results looked impressive. Most of them don't have a working app anymore, because they realized that the cleanup is just as important as the generation if you want something that actually holds together. I can only imagine what "vibe-debugging" looks like.

I'm glad I have a working app, but I'm not sure I can honestly call this vibe-coded. Most, if not all, of the files have been rewritten. When companies claim that a significant percentage of their code is AI-generated, do their developers agree? For me, it's unthinkable to deploy code I haven't vetted and understood. But I'm not the benchmark. I'm sure other developers may have different experience with different tools, but the pattern of cleaning up generated code still remains.

In the meantime, I think I've earned the right to say this the next time I ship an AI-assisted app:

"I apologize for so many lines of code - I didn't have time to write a shorter app."

I still have that flare in me, but I also don't always give in to those ideas. Instead, sometimes I chose to do something much simpler. I read. Sometimes it's a book, sometimes it's a blog post. But always, it's something that stimulates my mind more than any startup idea, or tech disruption.

There is a blog I follow, I'm not even sure how I stumbled upon it. I don't think it has a newsletter, and it's not in my RSS feed. But, it's in my mind. It's as if I can just feel it when the author posts something new. Right there on the kitchen table, I load it up, and I get a glimpse into someone else's life. I don't know much about this person, but reading her writing is soothing. It's not commercialized, the most I can say about it is, well it is human.

When I read something that is written, anything that's written, I expect to hear the voice of the person behind it. Whether it is a struggle, a victory, or just a small remark. It only makes sense when there is a person behind it. Sometimes people write, and in order to sound professional, they remove their voice from it. It becomes like reading a corporate memphis blog. Devoid of any humanity.

It's weird how I have these names in my head. Keenen Charles. I check his blog on Sunday evening as well. In fact, here are a few I read recently in no particular order:

• Henrik
• Hugo?
• Jerry (I particularly liked this specific article)
• Hong
• Don't know her name
• Keenen

This isn't to tell you that you need to read those articles or you will be left behind. It's not that deep. You can find things you like, and enjoy them at your own comfort. They don't have to be world changing, they don't have to turn you into a millionaire, they just have to make you smile or nod for a moment.

The world is constantly trying to remind us that we are at the edge of destruction. But you, the person sitting there, reading a random blog post from this random Guinean guy, yes you. Take it easy for the rest of the day.

TLDR; What I learned... and won't tell you

Here is the code I shared last year:

if (ipIsBlackListed() || isMalicious()) {
    header("Content-Encoding: gzip");
    header("Content-Length: ". filesize(ZIP_BOMB_FILE_10G)); // 10 MB
    readfile(ZIP_BOMB_FILE_10G);
    exit;
}

I deliberately didn't reveal what a function like isMalicious() does in the background. But that wasn't really the secret sauce bots needed to know to avoid my trap. In fact, I mentioned it casually:

One more thing, a zip bomb is not foolproof. It can be easily detected and circumvented. You could partially read the content after all. But for unsophisticated bots that are blindly crawling the web disrupting servers, this is a good enough tool for protecting your server.

One way to test whether my zipbomb was working was to place an abusive IP address in my blacklist and serve it a bomb. Those bots would typically access hundreds of URLs per second. But the moment they hit my trap, all requests from that IP would cease immediately. They don't wave a white flag or signal that they'll stop the abuse. They simply disappear on my end, and I imagine they crash on theirs.

For a lean server like mine, serving 10 MB per request at a rate of a couple per second is manageable. But serving 10 MB per request at a rate of hundreds per second takes a serious toll. Serving large static files had already been a pain through Apache2, which is why I moved static files to a separate nginx server to reduce the load. Now, bots that ingest my bombs, detect them, and continue requesting without ever crashing, have turned my defense into a double-edged sword.

Whenever there's an attack, my server becomes unresponsive, requests are dropped, and my monthly bandwidth gets eaten up. Worst of all, I'm left with a database full of spam. Thousands of fake emails in my newsletter and an overwhelmed comment section. After combing through the logs, I found a pattern and fixed the issue.

AI-driven bots, or simply bots that do more than scrape or spam, are far more sophisticated than their dumber counterparts. When a request fails, they keep trying. And in doing so, I serve multiple zipbombs, and end up effectively DDoS-ing my own server.

Looking at my web server settings: I run 2 instances of Apache, each with a minimum of 25 workers and a maximum of 75. Each worker consumes around 2 MB for a regular request, so I can technically handle 150 concurrent requests before the next one is queued. That's 300 MB of memory on my 1 GB RAM server, which should be plenty.

The problem is that Apache is not efficient at serving large files, especially when they pass through a PHP instance. Instead of consuming just 2 MB per worker, serving a 10 MB zipbomb pushes usage to around 1.5 GB of RAM to handle those requests. In the worst case, this sends the server into a panic and triggers an automatic restart. Meaning that during a bot swarm, my server becomes completely unresponsive.

And yet, here I am complaining, while you're reading this without experiencing any hiccups. So what did I do?

For one, I turned off the zipbomb defense entirely (...is what I tell people). As for spam, I've found another way to deal with it. I still get the occasional hit when individuals try to game my system manually, but for my broader defense mechanism, I'm keeping my mouth shut. I've learned my lesson.

I've spent countless evenings reading through spam and bot patterns to arrive at a solution. I wish I could share it, but I don't want to go back to the drawing board. Until the world collectively arrives at a reliable way to handle LLM-driven bots, my secret stays with me.

I knew writing was hard, but I didn't know how hard. I knew that maintaining a server was hard, but I didn't know the stress it would cause. Especially that first time I went viral. Seeing traffic pour in, reading back the article, and realizing it was littered with errors. I was scrambling to fix those errors while users hammered my server. I tried restarting it to relieve the load and update the content, but to no avail. It was a stressful experience. One I wouldn't trade for anything in the world.

13 years later, it feels like the longest debugging session I've ever run. Random people message me pointing out bugs. Some of it is complete nonsense. But others... well, I actually sent payment to a user who sent me a proof of concept showing how to compromise the entire server. I thought he'd done some serious hacking, but when I responded, he pointed me to one of my own articles where I had accidentally revealed a vulnerability in my framework.

The amount you learn from running your own blog can't be replicated by any other means. Unlike other side projects that come and go, the blog has to remain. Part of its value is its longevity. No matter what, I need to make sure it stays online. In the age of AI, it feels like anyone can spin up a blog and fill it with LLM-generated content to rival any established one. But there's something no LLM can replicate: longevity.

No matter what technology we come up with, no tool can create a 50-year-old oak tree. The only way to have one is to plant a seed and give it the time it needs to grow.

Your very first blog post may not be entirely relevant years later, but it's that seed. Over time, you develop a voice, a process, a personality. Even when your blog has an audience of one, it becomes a reflection of every hurdle you cleared. For me, it's the friction in my career, the lessons I learned, the friends I made along the way. And luckily, it's also the audience that keeps me honest and stops me from spewing nonsense.

Nothing brings a barrage of emails faster than being wrong.

Maybe that's why I subconsciously published it on April Fools' Day. Maybe that's the joke. I'm going to keep adding rings to my tree, audience or no audience, I'm building longevity.

Thank you for being part of this journey.

Extra: Some articles I wrote on April Fools day.

• So you've been blogging for 2 years
• Quietly waiting for Overnight Success
• Happy 5th Anniversary
• Count the number of words with MySQL
• How to self-publish a book in 7 years
• The Art of Absurd Commitment
• Happy 12th Birthday Blog
• What is Copilot exactly?

So I decided to give it a shot. I put all my prejudice aside and embraced the tool fully. AI is the future, and it shouldn't be hard to find a way to integrate it into my everyday workflow. I decided to give it a week, meaning I wouldn't complain even when I didn't get the result I wanted. Instead, for every frustration, I would use Copilot to help me turn that frown into a smile.

The result? I created a workflow. I automated a lot of the things I find super annoying: scrum ceremonies, BRD reviews, email writing. All the things I feel like I must do only for someone else to tick a box in their own workflow. After the first week, I decided to extend my trial for a full sprint. By embracing this tool, I felt like I had eliminated my manager's job. Instead of having him check boxes on his end, I could just present my reports at the end of the week. I created a template prompt where I could dump information throughout the day, and at the end of the day it would generate a report in whatever format I wanted.

I was so proud of my template that I shared it with my 10x coworker. He didn't respond with the enthusiasm I was expecting. He didn't understand what I was trying to do. In fact, he told me he had never used Copilot before. That was in direct contradiction of what he'd told me earlier. He was the only reason I gave this tool a shot, and here he was pretending we'd never had that conversation. Well, he clarified:

"I meant Copilot on VS Code."

Now, can you guess which Copilot I was using? Whatever Copilot is offered through Teams. And I say "whatever" because I genuinely don't know which one that is. Is it the same as accessing Copilot on the web? I wouldn't know. Our corporate firewall blocks that one. Teams seems to be the only approved method.

Anyway, what is Copilot exactly? Is it just a white-labeled ChatGPT? When I asked it directly, it said:

"It's Microsoft's AI companion, powered by advanced models (including OpenAI's), but shaped by Microsoft's ecosystem, design philosophy, and capabilities.
If ChatGPT is a powerful engine, Copilot is the full car built around it — with Microsoft's dashboard, safety systems, and features."

But where did the name come from? I'm sure I first heard it in the context of GitHub. The first AI code assistant shipped with VS Code. Even though they're both Microsoft products, they're two distinct products. If you use GitHub Copilot, your data isn't siphoned back to your Microsoft account (for now).

What I was using in Teams is Copilot for Microsoft 365, which is apparently different from Microsoft Copilot. The 365 version lives inside Microsoft 365 apps (that's Microsoft Office's new name, for those not keeping up). The key difference is that the 365 version can work with your emails, documents, OneDrive, and so on.

But if you have a Windows device, you also have Windows Copilot, distinct from the one in Microsoft 365. This one is your AI assistant inside the OS, meant to help you launch apps, summarize what's on your screen, and handle everyday tasks. In my experience, I couldn't get it to do any of those things. Apparently, I don't have a Copilot+ PC.

Reading through Microsoft's docs, I also found something called Copilot Chat. It's not quite a distinct product, but I'm not sure how else to classify it. Microsoft describes it as a general-purpose reasoning tool for writing, brainstorming, and coding. You can find it in M365 apps, and also within GitHub Copilot. That's the part that explains code, suggests fixes, and helps with debugging.

I asked Copilot Chat via GitHub Copilot to explain the difference between all the offerings. It summarized it neatly:

"Same family, different jobs."

I'm only scratching the surface of what Copilot is supposed to be, and I'm already tired. I felt inspired by a developer to explore it, only to find that he was touching just a small slice of this ecosystem. I still think it's worth encouraging teammates to embrace a tool that everyone else is losing sleep over. I should have stopped there, but I wanted to learn more about his workflow. I'm a developer after all, and whatever he's doing would be worth implementing with my team.

So I asked him. "What is your developer workflow using Copilot?" I was not prepared for the answer he gave me:

"Actually, I made a mistake. I meant Cursor."

And there it was. He wasn't talking about Copilot at all. Not the Teams one, not the GitHub one, not any of them. He had used "Copilot" the way most people use "Kleenex". To him, any AI code assistant was just a copilot. I had spent a whole sprint, struggling through this tool, inspired by someone who couldn't have cared less about Microsoft's ecosystem. There's a lesson there, I'm sure. I just didn't learn anything.

Why do we make two calls to get the... "We are fetching two types of orders to support legacy subscribers..." the documentation answered before I completed my question. This was standard number 15. The one to rule them all. But I still had one question. As the owner of the API, I read the documentation. Will other developers ever think to read it?

How do I get people to want to read the documentation before they use this API? Because in my experience, nobody reads the documentation.

Not to say that documentation is useless, but my mistake was thinking that the people who want to implement the API are interested in documentation at all. For every API ever built, there are two audiences to cater to, and confusing them is where most documentation goes wrong.

The first group is the consumers of the API. The only thing they want to know is: do the endpoints do what I need, and what parameters do they take? They are not reading your documentation like a book. They are scanning it like a menu. They want to find the thing they need, copy the example, and move on.

The second group is the maintainers of the API. The people who need to understand the why behind every decision. Why are there two calls? Why does this endpoint behave differently for legacy users? Why is this field nullable? These are the people who will be debugging at 2am, and they need the full picture.

The worst thing you can do is write one document that tries to serve both audiences equally. You end up with something that's too deep for the first group to skim, and not structured enough for the second group to find it useful.

For the first audience, the API should speak for itself. The best documentation you can provide is not text to read through, but a well-designed API. Follow clear, repeatable patterns where the user can anticipate, or even assume the available features.

If you have an endpoint called /user/orders, the assumption should be that /user/orders/1234 returns a specific order. If you add /users/orders/1234/cancel, there should probably be a /users/orders/1234/update too. When the pattern is consistent, the consumer doesn't need to read anything, they just guess correctly.

When you do write documentation for this audience, resist the urge to explain your internals. They don't need to know that you're fetching from two different database tables to support legacy subscribers. What they need to know is: supports both new and legacy orders. One sentence. Done.

I like this idiom: "Too much information and no information, accomplish the same goal."

This is a mistake I see most often. It's a painful one because it comes from a good place. The writer of the documentation, usually the person who built the thing, feels a sense of responsibility. They want to be thorough. They want no one to be confused. So they write everything down.

The result is a documentation page that looks like this:

GET /user/orders
This endpoint retrieves orders for a given user. It was introduced in v2.3 of the API following the migration from the legacy order management system (OMS) in Q3 2021. Internally, the resolver makes two sequential calls (one to the new orders table and one to the legacy_orders table) and merges the results using the order ID as a deduplication key. Note that legacy orders may not contain a shipping_address field, which was not captured before 2019. If you are building a UI, you should account for this possibility. The endpoint also supports cursor-based pagination, though offset-based pagination is available for backward compatibility with clients built before v2.1. Additionally, orders in a PENDING_REVIEW state may not appear immediately...

A developer scanning this page will read the first sentence, close the tab, and think about designing API standard number 16. They'll go look at the codebase instead, or ping a teammate, or just guess. The documentation existed, it just didn't get read. Which means it accomplished exactly the same thing as having no documentation at all.

The same way you don't write a comment to explain every line of code, a documentation doesn't benefit from too much information.

My go to solution isn't to omit information, but to write it in layers.

Collapsible sections are one of the most underrated tools in documentation design. They let the consumer skim the surface: endpoint name, what it returns, a working example. And they let the maintainer dive deeper into the implementation notes, the edge cases, and the historical context.

The same principle applies to how you order information. Lead with what the API does. Follow with how to use it. Bury the why at the bottom, behind a toggle or a "Details" section, available to those who need it, invisible to those who don't.

Think of it like a well-designed error message. A good error message tells you what went wrong in plain language. A great error message also includes an expandable stack trace, but it doesn't show you the stack trace first.

Your documentation has the same job. Give people the answer they're looking for, and then offer the depth to those willing to dig.

The second audience, the maintainers, do need the full picture. The two database calls, the deduplication logic, the historical reason the shipping_address field is sometimes null. This is the documentation that prevents a future developer from "fixing" something that wasn't broken, or removing what looks like redundant code.

But this documentation doesn't have to live on the same page as the quick-start guide. Deep implementation notes belong in inline code comments or a separate internal wiki. The public-facing API reference should stay clean.

When you separate operational documentation (for consumers) from institutional documentation (for maintainers), both documents get better. The consumer doc gets shorter and clearer. The maintainer doc gets deeper because it's no longer trying to also be beginner-friendly.

The goal of documentation isn't completeness. Completeness is what you write for yourself, to feel like you've done your job. The goal of documentation is to transfer the right information into the right person's head at the right moment.

That senior developer who wrote the documentation I cried over understood this. She didn't write everything she knew. She wrote exactly what someone reading the code would need to know, at the exact moment they'd need it. And the API design allowed anyone consuming it to make correct assumptions (intuitive design) on how it works. Both groups are happy.