Engineering
A benchmark for docs that AI agents can actually use
Public benchmarks need explicit scoring, narrow claims, and vendor neutrality to create useful feedback loops.
F
Faizan Khan•9 min readLatest Updates
The DocsAlot Blog
Insights on documentation, developer experience, and best practices for building better software.
Engineering
I Redesigned My Landing Page So AI Agents Can Read It
I spent the week redesigning DocsAlot's landing page. The harder part wasn't the CSS. It was making the same page work for humans in a browser and for agents that would rather have markdown.
F
Faizan KhanIndustry Analysis
Why I'm Building Yet Another Docs Product
The docs market looks crowded on paper, but most teams still ship docs that are increasingly unreadable to both humans and agents. This is the memo for why DocsAlot should exist.
F
Faizan KhanEngineering
Why MCP Still Matters If You Already Have a CLI
A good CLI solves part of the problem. It does not solve cross-OS distribution, desktop client compatibility, or non-technical adoption. For Docsalot, MCP matters because it gives us one protocol surface instead of a growing pile of binaries.
F
Faizan KhanEngineering
Man Files for Agent-Friendly CLIs: Why They Matter and How We Built Ours
Without detailed in-CLI docs, agents guess and fail. Here’s the man-file pattern we implemented, inspired by recent agent-first CLI writing, plus how matching works today and what we’re improving next.
F
Faizan KhanEngineering
skill.md: An open standard for agent skills
Every documentation site on Docsalot now serves a skill.md file that AI agents can install with one command. Here's the standard, what we learned from Anthropic's best practices, and how you can implement it for your own docs.
F
Faizan KhanIndustry Analysis
Why Running an Inference Startup Is So Damn Hard
Inference-as-a-service looks like easy revenue from the outside. In practice, it's a brutal utilization game where bad unit economics can kill you even when demand is real.
F
Faizan KhanEngineering
MCP Servers: What They Are, Why They Matter, and What Can Go Wrong
Everyone's adding MCP servers to everything. Here's how the protocol actually works under the hood, why documentation teams should care, the security risks that come with it, and what it looks like in practice.
F
Faizan KhanEngineering
llms.txt Isn't Enough
llms.txt solves discovery. Content negotiation solves consumption. One of these matters 27x more than the other.
F
Faizan KhanBest Practices
How to Make Your Documentation AI Readable (A Practical Guide)
Your docs will be read by AI agents more than humans. Here's how to structure llms.txt, serve markdown versions, and actually get found by AI tools.
F
Faizan KhanTechnology
install.md reinvents Gherkin, poorly
A new 'standard' for AI-powered installation has emerged. But is it solving a real problem, or is it a solution that wouldn't exist if building things wasn't so cheap now?
F
Faizan KhanTechnology
Your Documentation Is Already Lying to You
I spent three years watching documentation rot. Here's why it happens, what's actually changing, and the uncomfortable truth about keeping docs alive.
F
Faizan KhanBest Practices
I Let AI Write My Docs for Six Months. Here's What It Can't Do.
After six months of using AI to generate documentation, I have strong opinions about where it's magic and where it's garbage. This is that list.
F
Faizan KhanBest Practices
The Documentation Generator That Finally Didn't Suck
I've tried every documentation generator since 2018. Most are garbage. Here's what actually works, and the hard-won principles behind why.
F
Faizan KhanBest Practices
Why Docs-as-Code is the Future of Documentation in 2026
Learn why treating documentation as code through version control, automation, and developer workflows is the best approach in 2026.
F
Faizan KhanTechnical
Documentation Rots. Here's How to Stop It.
A deep dive into why documentation drifts from code, the patterns that cause it, and the automation strategies that actually work to fix it.
F
Faizan KhanTools
Top 8 Documentation Automation Tools for Developers in 2026
Compare the best documentation automation tools in 2026, including Docsalot, and learn which solution fits your development workflow.
F
Faizan KhanBest Practices
Why Most Developer Documentation Sucks (And How To Actually Fix It)
A brutally honest look at what makes documentation terrible, why we keep shipping bad docs, and the specific techniques that actually work.
F
Faizan Khan