The blog had the facts and still left people out

I asked Manus for more structured source material: git, Discord, Jira, the vault, session records. The plan was to improve the technical posts. It was also to build a second, plain-language version for business owners and early AI adopters. The request named both audiences, so it sounded complete. It was not complete. The data sources took most of the weight. The plain-language reader got one clause near the end. I had turned the audience into a data problem, and that was the wrong model.

The failure in the Manus task was specific. I had sent Manus toward an inventory of source material when the missing object was a route through that inventory. More records could make a technical post more grounded. They could not by themselves tell a reader why unfamiliar words felt intimidating, or make the next useful question visible. The source request itself said that jargon was confusing and scary. It also asked for something straight, simple, practical, and visible. I had stated the need and then treated it as a secondary formatting concern.

That is how the gap stayed hidden. A technical post can faithfully record a decision, a tool, or a failed check. A reader outside that vocabulary arrives with a different problem. They need enough context to know what changed, why it matters, and where they can stand before the technical detail starts moving. Replacing difficult words is not enough. The missing work was to preserve the event while changing the entry point.

I stopped calling that work a nice extra. It was a communication layer. The technical post and the plain-language post were doing related jobs, but they were not duplicates. One kept the operational detail available. The other made the event legible before that detail became a wall. That distinction changed the count from a content target into a coverage problem.

Then the inventory became concrete. The work log records 74 companion posts written and gated. It also records 113 unscored technical posts triaged into three outcomes: publish-ready, one-edit, and retire. I did not need every technical post to receive the same treatment. I needed the existing material to be honest about its state before it could carry a second route for a different reader.

The gate changed too. I had treated the leak check as a publishing concern, something that happened at the end after a draft was otherwise finished. The work moved that check from publish time to draft time, so a draft was safe when it was written. That is a small shift in sequence, but it changes the artifact under review. A late check protects the release. A draft-time check protects the words that every later edit, companion post, and review will inherit.

The companion format gave that responsibility a place to live. It did not ask a technical draft to become less technical. It made a second artifact accountable for the first moment of understanding. That is a narrow job, but it is a real one. Without it, a reader is asked to translate the post before the post can help.

I also stopped treating the three triage labels as back-office labels. They made the source material visible as a set of decisions. A post could be publish-ready. It could need one edit. It could be retired. Those are different conditions, and each one affects whether a companion has something sound to explain. A plain-language layer cannot rescue a technical post whose own status is still unclear.

The draft-time leak check belongs in the same picture. Plain language is not permission to become loose with the source or careless with what the text exposes. The posts had to be both understandable and safe at the moment of drafting. That sequence let the companion work begin from a bounded artifact instead of making readability another reason to delay the check.

The uncomfortable part is that none of this began with a writing problem. Manus had more possible source material. The technical posts had a triage. The gate had a place in the workflow. The gap was that the system had no explicit responsibility for translating an event into plain language without sanding the event down. I had assumed technical accuracy would travel on its own.

I am still wary of calling the 74 companion posts an expansion. That makes them sound optional. The first number that matters is 74, because that is how many paths the technical blog did not have before.

dxdev LESSON · paste into your AI coding agent
LESSON: Naming Both Audiences Is Not the Same as Serving Both
SOURCE: dxdev.com/blog/2026-08-22_plain-language-layer-discovered-missing
WHAT HAPPENED: A request to expand a technical blog's source material named a second, plain-language audience in one clause near the end, then spent the rest of the request on data inputs. The plan implicitly treated more data as sufficient for both audiences, until a reread showed the plain-language reader had no dedicated path through the material, only a shared inventory. The fix built a companion-post format with its own gate, moved a leak/safety check from publish time to draft time, and triaged the existing technical backlog into three honest states before any companion could be written against it.
THE RULE: Naming a second audience inside a request that is otherwise built around one audience's inputs does not serve that audience; check whether the ask allocates real, dedicated work to each named audience, not just a mention.
CHECK MY CODE, then report PASS or FAIL with file:line for each:
  1. Any request, spec, or plan that names more than one audience/user type but allocates the actual scope of work (inputs, steps, acceptance criteria) to only one of them
  2. Any safety/compliance check that runs at publish/release time when it could run at draft/creation time, protecting the artifact from the moment it exists rather than only at the end
  3. Any content or feature backlog with unscored/untriaged items being asked to support new derivative work (a companion format, a translation, a summary) before their own status is resolved
THEN PRINT: a table (check, PASS/FAIL, evidence, fix) + a verdict (applies / partially / OUT_OF_SCOPE / no) + the single most important next action.