The README is dead, long live onboarding: documenting in the age of agents
🔗 Learn more about me, my work and how to stay in touch: maeste.it: personal bio, projects and social links.
Week of getting back from PyCon Italia, and with this issue’s deep dive I start from a provocation I have been carrying since those days: nobody reads the documentation anymore, neither developers nor end users. I tell you why this happens and which paths I am exploring to fix it, from the README as an entry point to terminal wizards, hierarchical help and onboarding skills for agents, with concrete examples taken from LINCE and antirez’s DS4. In the links section you will find the themes of the week: Pope Leo XIV’s encyclical on AI, the new DeepSWE benchmark that crowns Codex on coding, Anthropic’s Memory Files and Claude Opus 4.8 with Dynamic Workflows, the price war reignited by DeepSeek, and Reasonix, a coding agent built for open weight models. Enjoy the read.
My agenda
On Wednesday the conversation with Andrea Saltarello (Improove, AIConf, Politecnico di Milano) came out: why AI adoption in companies is a cultural problem before a technical one, and how to train juniors in the age of agents. Listen
On Saturday “The Pope understood LLMs better than we did” came out: Leo XIV’s encyclical opens, then saturated benchmarks, DeepSeek V4 and append-only context, microkernel harnesses and Claude vs Codex. Episode
By now you know about our GitHub repository with tools and configurations for AI coding from the terminal on Linux. It now has its own site with single-script installation Lince.sh
We released AntiVocale (Google Play, GitHub), a software to translate voice messages into text
On my own:
I was at PyCon Italia as a speaker: you can find all the materials from my two talks, as always, on maeste.it in the section dedicated to talks. I will also put the videos there as soon as they are available
On June 12 I will be in Catania as a speaker at Coderful
On June 24 I will be in Milan as a speaker at AIConf
Who actually reads the documentation? From the README to onboarding skills
Nobody reads the documentation anymore. I say this mostly about developers, but it probably applies a bit to everyone, end users included. It is something that became clearly evident talking to so many people at PyCon Italia, which I just got back from and where I had two talks. One in particular was a workshop that dealt with exactly this: how to provide the right setup to a project, open source or not, so that agents can code well, that is, have all the information they need. My provocation during the workshop was precisely that: agents often get things wrong, but not because they are stupid, rather because they ignore the basics of the project.
The same thing happens with end users, be they developers or users of the project we are releasing, because really nobody reads the documentation anymore. In this period of information overload, due in part to AI, nobody bothers to do it: there are so many projects, and so many things people want to try, that the documentation just sits there, unread. I will add one more thing: the fact that we have gone back to the terminal, which I talk about often, is wonderful for many reasons on one hand, but on the other it makes the interface a bit less intuitive, at least for a certain slice of users.
I have been racking my brains for a while on the solution, because a user who does not read the documentation will probably not use our project to its full potential, and risks getting fed up soon: not because the project does not work, but because they could not get it to work for what they needed. And that is a shame, because it is entirely avoidable.
The solutions I have explored, in LINCE and recently with a pull request for antirez’s DS4, span several fronts. The first is making the terminal interface a bit more window-based, or wizard-guided, like Lince does with its agent creation wizard (the capital “N”), or like the LINCE dashboard itself, which brings icons and windows inside the terminal. The second is rethinking the README: the README as a single, exhaustive document is dead, and it must instead become an initial entry point, a sort of TLDR. The detailed documentation can live elsewhere, but by scraping just the README the user immediately understands what the project is for and what they can do with it. Of course it must also contain an invitation to read the rest. Along the same lines, configuration files should be as self-documented as possible, and it should be extremely easy to create versions tailored to the needs of whoever uses them: that is what we try to do with the learning mode of Lince.sh.
But there is one approach I like the most right now: creating onboarding skills for the agents themselves. The user, instead of reading the documentation line by line, arrives at the project, launches the skill and starts conversing with their own agent, instructed to stick only to the documentation and the command help. They thus get all the information they need in a way that has by now become the habit, conversation, but stays anchored to what you have actually documented. It is exactly the spirit of the skill I proposed to antirez for DS4 and of the one we already have in Lince.sh.
To do this, however, the command help also needs to be well organized, and here we come back to the starting point: it needs to be made usable by agents, even when it will not be the agents using it directly, but they will use it only to build the onboarding. A good example are Lince’s commands, but above all those of DS4, where antirez did an excellent job on hierarchical help, which I will try to take inspiration from for Lince as well.
And then, last but not least, we increasingly need different and somewhat more human content, to avoid the AI slop effect. That is also why I have a podcast, and why I write this newsletter: as you know it is no longer AI generated, the AI acts as my editor but what you read is written by me. The same goes for the videos that explain certain features. There, that is something I have not done enough for Lince.sh, and I am genuinely interested to know whether it is something you would like.
The links that struck me this week
Notes on Pope Leo XIV’s encyclical on AI
I talked at length about the papal encyclical on this week’s podcast, and I think it can be condensed like this: the Pope understood Large Language Models far better than Bernie Sanders and Walter Veltroni.
DeepSWE: the new coding benchmark
A new benchmark has appeared in the AI world, in particular for coding agents, and it is significant precisely because it is very new and very carefully curated, and therefore not yet saturated. The results are impressive and confirm the impression that, right now, Codex is better than any other agent and any other model at coding tasks.
Anthropic plans Claude memory update with new Memory Files
Anthropic, however, is not standing still and is working a lot on the memory aspects of its harness. A link definitely worth reading.
Claude Opus 4.8
And as confirmation that Anthropic is certainly not standing still, Claude Opus 4.8 is out, bringing an incremental improvement over 4.7. Perhaps the most significant thing is that as of 4.8 the Dynamic Workflows are available, which look a lot like the agent swarms Google already launched with Antigravity. And exactly like the Antigravity swarms, they are extremely expensive: before you start using them, run a few tests on small tasks to understand how much impact they can have on your wallet.
DeepSeek made its 75% discount permanent
The price war has officially begun, and DeepSeek is setting the pace. What used to be a promotion becomes DeepSeek V4’s base price: cut to a quarter of the price initially announced.
Reasonix
Reasonix is a DeepSeek-native coding agent for the terminal. The interesting part is that it has been optimized to leverage DeepSeek’s caching mechanisms, going essentially append-only: something you can afford with a million tokens, and which drastically reduces costs. But in general it is interesting that we are starting to see harnesses designed and built to make the most of open weight models’ capabilities. Something that Anthropic, OpenAI and Google are certainly already doing with their harnesses, optimized for their own models.