dsavvinov Explain properly
If this skill ran, something is wrong
The user did not follow the text you wrote. That is a defect in the text, not in the reader. Do not defend the previous version, do not re-send it with a preamble, and do not apologise at length — diagnose what made it unreadable and write it again under the guidelines below.
Rewrite; do not patch. Appending a paragraph of clarification to a text that already lost the reader makes it longer and no clearer.
Diagnose first: which bucket is it?
Misunderstanding almost always comes from one of three buckets. Identify the one that applies before rewriting — the fix differs per bucket.
1. Conceptual overload
You used too many semantically heavy words, and the user does not carry the meaning you assumed. Frequent forms:
- Legitimate terms the user does not know. Explain them, or use a plainer wording.
- Invented terms. Prefer an existing well-known term. If none exists, introduce and define yours explicitly before using it.
- Inconsistent terms. The same thing referred to under slightly different wordings reads as several different things. Pick one wording and keep it.
- "How" before "why". You described implementation detail before saying what the code achieves at a general level. Say what it is for, then how it does it.
- Overquoting source code. Every symbol you name is one more term the reader must hold. Quote only the code the explanation genuinely turns on.
- Smart lingo. "This buys us an opaque transformation of the data" instead of "Clients won't know how the data is transformed, so we can swap the implementation later if we need to." Say the second one.
2. Jumpy narrative
You referred to things you never explained, or explained only further down, in text the reader had not reached yet. Reorder so every concept is introduced before its first use, and fill the gaps you skipped.
3. Overcompressed text
You bought conciseness by throwing away the lexical glue that makes prose readable, instead of by limiting what you describe. The hallmark is telegraphic notation:
network call + ui responsiveness -> async call
when what the reader needed was:
To check for updates, we need to access the network. That call can be slow — the user may be on a spotty WiFi connection. If we made it a blocking call, the whole UI would appear frozen. So we do it in a background task.
The guidelines
This is where most write-ups fail, and the failure is not length but density.
Be concise, but buy the concision by moderating what you present and what you omit, never by compressing what stays. Spanning a lot of terms, concepts and class names and then stripping the punctuation and prose to make it lexically short leaves something still impossible to read.
Instead: select the limited set of terms, abstractions and concepts genuinely needed to understand the system state, then introduce them one by one, sequentially, explaining each one — before the sentence that says what went wrong. Abstract shorthand is unreadable and actively harmful to the final text.
That set should be four to six concepts. Needing more is a strong signal that something is off — there are legitimate exceptions, but they appear only in genuinely hard and big problems. In case of doubt, always assume the case you're working on is not one of those "hard and big problems": if the user misses some depth, it's easy to follow up and ask for more details; the extra noise is not that easily fixable.
If you are ABSOLUTELY certain a case cannot be explained in six, the answer is still to moderate the reader's context, by splitting the concepts into cohesive chunks:
- explain one chunk in depth, then summarise it, so the reader can partially offload it and carry only the summary forward;
- move to the next chunk;
- keep the chunks in linear sequence — an earlier chunk never needs knowledge from a later one, and a later chunk builds on the earlier ones.
Before you send it
- Count the concepts you introduced. Over six, cut scope — not words.
- Check that each one is introduced before its first use.
- Check that the same thing is called the same name throughout.
- Read the text as someone who knows the domain but not this code. Every sentence they could not answer "what is that?" for is a defect.