Structure: let the reader's task set the hierarchy
Use predictive headings. Definitions and prerequisites come before dependent operations, but do not front-load all background.
Evidence: primary sources, with version and date
Use primary documentation, specifications, worked examples, constraints, and edge cases. Give the version or date where the technology changes.
Prose: consistency beats stylistic variety
Use one name per concept. Repeat key terms. Keep conditions and exceptions visible.
Explain the minimum required for the reader's next move
The Carl Zimmer material in your science-writing highlights gives a better target than "make the explanation complete". A complete explanation can be unusable if it consumes the whole piece.
Ask:
What is the minimum explanation the reader needs to understand the argument, story, or operation at this point?
This is not permission to omit a load-bearing mechanism. It is a sequencing rule. Give prerequisites when they become necessary, not merely because you know them.
Distribute explanation through the piece
Large blocks of pure explanation often stop narrative and argumentative movement. When possible, alternate:
concrete problem → necessary explanation → consequence → next problem
This lets explanation serve motion instead of pausing it.
For a technical article, the same idea becomes progressive disclosure. Give the reader enough to perform or understand the current step, then introduce the next layer when the dependency appears.
Sometimes the story of the explanation is clearer than the explanation alone
When an idea was discovered through successive failed models, experiments, or corrections, the reader may understand it better by seeing why earlier explanations failed.
The discovery path is especially useful in these cases:
- the final mechanism is counterintuitive
- the historical sequence reveals why a distinction matters
- the reader is likely to hold one of the earlier models
- the uncertainty itself is part of the subject
Do not turn every explainer into a history lesson. Use the discovery path only when it reduces cognitive load rather than increasing it.
Use analogy after the mechanism, not instead of it
The science-writing and Marks materials agree here. An analogy can compress or illuminate a mechanism once the mechanism is visible. It is dangerous when the analogy becomes the only reason the reader has to believe the claim.
A useful order is:
- State the phenomenon.
- Explain the relevant mechanism.
- Use the analogy to make the mechanism easier to hold.
- Return to the real case and name where the analogy breaks.
Ending: often a checklist, not a conclusion
Often no literary conclusion is needed. Finish with a checklist, decision map, or reference summary.
Main risks
Watch for these failures:
- coverage without prioritisation
- abstract description without example
- outdated facts presented as timeless
- examples that do not cover edge conditions
- decorative prose interfering with retrieval
AI role: research and check consistency
Research assistant, structure checker, example tester, terminology consistency checker, change-log reviewer.