<unnamed>

Public Key

npub1h9dv6d8w2qzq3345u5wst7an9sx8052ws6dg2mwc20n7sefyuyes9p7f2d

Profile Code

nprofile1qqstjkkdxnh9qpqgc66w28g9lwejcrrh698gdx59dhv98elgv5jwzvcpz3mhxue69uhhyetvv9ujuerpd46hxtnfduqs6amnwvaz7tmwdaejumr0ds2cvx0z

Publishing to

relay.damus.io

nostr.wine

nos.lol

Last Notes

2026-10-28 03:08:18 GMT

am2.co just got a new look
This site was starting to get a little dusty. Things change fast in tech—as database folk, we often think of technologies, languages, and capabilities—but design and UX are constantly evolving, too. The styling and the design were both starting to look a bit dated, and “a bit dated” is not a term I want associated with my professional blog/website. I haven’t been writing a ton of new content, so I also haven’t been putting in the incremental upkeep. Anyway…let’s talk about my updates.
https://am2.co/2026/10/27/new-look/
#look #anyway
#rss #feeds #linksharing #qwibbit

2026-10-27 02:46:01 GMT

Crawling out of my hole to write more
I haven’t been blogging much over the past couple of years. I’m crawling out of my hole to write again, and I hope to post more regularly. That’s what everyone says when they come back, though, so we’ll see if I actually follow through.
What’s bringing me back to writing? One reason is that AI has become a practical tool in my day-to-day work, and I want to write about how I use it. Expect the familiar topics—HA/DR, performance tuning, and professional development—with AI alongside SSMS as a standard part of the toolkit.
https://am2.co/2026/10/26/back-to-writing/
#hole #ssms #expect
#rss #feeds #linksharing #qwibbit

2026-10-16 02:52:46 GMT

Your documentation belongs with your code
If this dog-umentation is right, can you spot all the problems in the generated arf-ifact?
For years, I’ve advocated for keeping developer documentation in the same code repository as the code it describes. In the age of AI, that practice has become even more important.
The reason is simple: the easier we make it to maintain documentation, the more likely it is to stay current.
Reduce the friction
Developers write code in their IDE and manage it in Git. But too often, the accompanying documentation lives somewhere else — Confluence, a wiki, or a separate documentation platform.
Every context switch adds friction. Developers have to leave their workflow, find the right page, make the change, and remember to publish it. It’s no surprise that documentation updates get overlooked.
Keep the docs in the repo, and they become part of the same workflow. Developers can update code and documentation together, in the same branch and pull request.
When documentation toil meets developers where they work, the toil is more likely to be completed instead of avoided. Reduce the barrier to completion, so that it’s nearly as easy to do it as it is to ignore it.
End-user documentation is a different concern. It can be generated or published from the source documentation, giving user-focused polish, accessible content, etc without requiring access to the code.
AI needs context, too
Everything that applies to human developers applies to AI coding agents. But there’s another compelling reason to keep documentation close to the code: documentation gives agents context that the code alone can’t provide.
Code describes what a system does. Documentation explains what it’s supposed to do, why it works that way, and which constraints matter.
Without that context, an agent must infer intent from the implementation. Inferences and assumptions aren’t always correct–and starting with a garbage inference means you get garbage output. With the extra context of documentation, your coding agent has a better foundation for making changes that preserve intended behavior.
More relevant context doesn’t guarantee better code, but it gives agents a better chance of getting it right.
Better context means better reviews
Documentation also gives AI agents another way to evaluate their own work. (You are doing adversarial code reviews when you use a coding agent, right?)
When reviewing a change, an agent can compare the implementation against the documented intent.
Does the code meet the requirements?
Does it preserve the expected behavior?
Has the change introduced a discrepancy between what the system is supposed to do and what it actually does?
Tests and static analysis remain essential, but documentation adds another point of reference — one that can help expose problems neither the code nor the tests make obvious.
Of course, documentation can be wrong, too. Keeping it alongside the code makes it easier to maintain, but we still need to ensure both reflect the intended behavior.
Make documentation part of engineering
AI isn’t eliminating the need for good documentation. It’s increasing its value.
Keep developer documentation alongside the code.
Make updates part of the same workflow.
Update and publish end-user documentation from that source as needed.
Do this for your developers, and you’ll reduce the friction that keeps documentation from getting updated.
Do it for your AI agents, and you’ll give them the context they need to write and review better code.
The principle hasn’t changed. But in the age of AI, the payoff is bigger than ever.
The post Your documentation belongs with your code appeared first on Andy M Mallon - AM².
https://am2.co/2026/10/your-documentation-belongs-with-the-code/?utm_source=rss&utm_medium=rss&utm_campaign=your-documentation-belongs-with-the-code
http://am2.co/wp-content/uploads/FreddieMercury-as-FreddieMercury-1024x637.jpg