Why do developers of systems, algorithms, programs, CLIs, UIs, and Infra suck so much at documentation in the age of 2026?

You drop into a system with no docs, poorly written docs, and bad code structure. You are left sending your agents exploring this mess, and then they still can’t figure it out because you suck at your job. You supposedly made all these modules and algorithms, yet you told no one how to use or extend them.

I don’t understand how you sat there for a sprint or two making a program and then can’t figure out how to write text about using it, and allowing team members and agents to use it efficiently. What is wrong with you? You wrote all this “hard” code, but can’t communicate through text how it works?

You cant drop garbage algorithms on your team with no idea how the modules or system works. You already suck at programming and now you suck at writing. The year is 2026 and this is unacceptable. Here let me show you the light. We have something that can help you. The GREAT RUBBER DUCK is here and they are LLMs

Documentation in the Age of 2026

LLMs are still dumb and don’t understand the system world model anywhere near the human level. Now before you get your panties in a wad please consider how amazing and dumb LLMs are. One moment they decompile a game and the next they created a broken CLI for combining datasets. However we have the best rubber duck in the year 2026. There is no excuse for you to be making bad documentation for your programs. Yes even those using local models do not have this excuse.

Keep it Direct

People have these great LLMs and they just let the slope take over and send me a program with too much documentation. I can’t find any signal within the noise. Agents are awful at writing prose. You need to get your agents to make direct factual statements and help with formatting markdown tables and how to use your program. For areas that need prose like algorithm descriptions or key areas of the program that should be done by you. You hate reading AI and so do your coworkers.

Tokens are not free and context must be managed. Your long documents confuse the agents and people. You will see your agent mixing up different documents and referencing wrong markdowns. This will lead to wrong code being written and then wrong docs being generated. Then it becomes the snake eating itself.

Your documentation should be written in a way where new people and agents can quickly read and understand the structure and how to use the program. This is really easy to test now. Just make a fresh session with your agent and ask it to explain how the program works and how to change and modify it. If it can figure this out in a low token count then you may be on the right track. This transfers to people as well. I should be able to go into a program and quickly be able to figure out the big picture and how to use it.

Keep Modules Organized in Locality of Scope

Modules should contain files and code that relate to each other. Locality of scope helps agents and people. When things that relate to each other are close together it makes searching much easier. This really should not need to be explained. This is very obvious.

When you scatter files and code throughout unrelated pieces then agents are to bloat their context with searching the codebase. This can lead to more errors.

Conclusion: Keep it Personal

Remember that we need to keep things people centric. We work on teams of people and we have to manage these algorithms and systems. We need to use our own words when explaining things in our docs. Sure that markdown table does not need to be typed by you but explaining the algorithm that you made needs to be explained and understood by you.

We need to reduce the bloat and have clear and concise documentation to help guide team members and their agents. Please respect your coworkers. We can create great software that is well documented and we have to keep people as the center consumer.

Despite the narrative people are much more capable and important than your dumb agent. We need to work together to create great software.