How explaining code works
The map of what can be explained, one topic one conversation, and documents that stay in the project.
Explaining is the answer to a question nobody knows how to ask well: “what kind of project is this and how does it work?” Instead of asking around in a chat and then hunting the answer in a three-hundred-line conversation, you get a directory of topics and one document from each, which you can come back to.
The map of what can be explained
The first thing you see in the Project → Explanations tab is an invitation to build the map. The map is a list of what is worth explaining in this project — layers, modules, the flow of data, particular files. The Agent builds it, because only it knows what is in the project.
Building runs in the background and the result is not a message in a conversation but a file in the project. You do not have to be there for it — the map appears in the app by itself as soon as the Agent writes it.
In the map the topics come in groups. The first group is the general one: the architecture, the design, the flow of data. Those are questions that can be asked without knowing a single file — that is why they are first. The particular parts are below them.
The project changes, the map does not. “Build the map again” is therefore a button to use when the project has moved on — after a bigger refactor an old map is more confusing than useful.
One topic, one conversation
A tap picks one topic or several, and then you press Explain. The reply does not go into the main Conversation, but into one of its own, named after the topic.
That is deliberate, not a detail. Whoever is dealing with work does not want the chat flooded with an exposition of the architecture; whoever is learning the project wants to come back to the topic, not fish for it in a chat. In that conversation you can moreover keep asking — and the questions stay with the topic they belong to.
In progress and finished
Above the map there are two sections. Topics in progress are those a conversation is already running about. Finished explanations are files in the project, in docs/explanations/ — one topic, one file.
The difference between them is in what survives. A conversation belongs to the Server and disappears after switching projects or a cleanup. A file in the project stays, goes into git, and a colleague who does not have coden can read it too.
What is already explained is not offered in the map a second time. Were it offered, you would not know whether you are continuing or starting from scratch.
What it is good for
- A new project. You build the map, have the general group explained, and in twenty minutes you have an overview you would otherwise put together over two days.
- Unfamiliar code. The very file you are about to touch, explained to you before you write into it.
- Documentation that comes about as a by-product. The files in
docs/explanations/are written to be read, not for a model — and they stay in the project. - Reading without a connection. Finished explanations are in the mirror of Documents, so they open offline too.
Without a connection
Commissioning an explanation without a connection to the Server is not possible — somebody has to work on the other side. Ones already saved keep being readable, and the app says so outright instead of leaving the button unresponsive.
Stuck somewhere other than what is here? Write to support@coden-app.com.