Contents
When an AI explanation is unclear, ask the model to fully explain the intended meaning before shortening it. The explain-before-shorten skill turns this instruction into a reusable editing process while preserving technical terms and important conditions.
Key Points#
- Decide what readers need to understand before changing individual words.
- Write a draft that makes sense as a spoken explanation, then shorten it.
- Keep conditions and constraints close to the statements they apply to.
- Check that the final text makes sense on its own, and inspect the rendered page when layout matters.
Why Short Explanations Can Fail#
A sentence can be technically correct without explaining the main point. Consider this example from the supplied materials.
> Completed means that the code has finished running. It does not mean that there were zero invalid inputs.
This distinction may matter, but the second sentence introduces a caution before explaining the relationship between execution status and input validity. If readers want to know what Completed means, this caveat may distract them from the main point. If they want to know how to interpret validation results, the explanation is insufficient.
The right revision depends on the purpose. For a status definition, “Completed means that the code has finished running” may be enough. To explain validation, you need verified information about how invalid inputs affect the results. Replacing a caveat with an invented explanation may improve readability while reducing reliability.
What This Skill Changes#
The explain-before-shorten skill changes the order of editing. Instead of immediately cutting words, it asks the model to clarify what the explanation needs to convey and first produce a full explanation.
“Explain it aloud” is a way of thinking, not a required writing style. The finished text can remain formal. Keep the technical terms readers need. The goal is to explain their meaning, not replace them with vague everyday language.
The supplied skill targets Japanese explanations in slides, technical documents, and emails. Its editing method can also be applied to English writing, but the materials do not establish how consistently it works across languages or models.
Review in Six Steps#
Apply the following process to a paragraph, slide, or table entry.
1. Identify the intended meaning. Write one sentence stating what you want readers to understand. Avoid adding a suggested action to text that only needs to explain a concept. 2. Explain without a length limit. Describe what happens, including causes or conditions where needed. Distinguish verified facts from recommendations and possibilities. 3. Separate different topics. Put mechanisms, requirements, and exceptions in separate sentences or locations. Keep each condition close to the statement it applies to. 4. Shorten without losing meaning. Remove repetition and unnecessary introductions. Preserve the subject, action, causal relationships, and important constraints. 5. Read only the finished text. Check whether it is understandable without the longer draft or additional spoken explanation. 6. Check the edited result. Confirm that the saved text matches the intended changes. For slides with fixed dimensions, also check line breaks and overlap with footers.
If shortening makes the text harder to understand, restore the words you removed. A slightly longer sentence is better than one that requires readers to fill in the explanation themselves.
Be Specific About the Revision#
A useful request includes both the unclear text and its purpose.
> Use explain-before-shorten to revise this paragraph. Readers need to understand what Completed means. Explain the meaning first, then shorten it. Preserve technical conditions, and flag missing facts rather than inventing them.
Include surrounding paragraphs or related tables if they affect the meaning. Simply asking “Make this sound more natural” leaves the model to guess whether the problem is vocabulary, structure, or missing information.
The supplied skill usually returns the finished text first, followed by a brief explanation of important changes. There is no need to show the longer working draft every time. This keeps the response focused on text the user can use.
Make Constraints Explicit#
Even when shortening, do not remove conditions that determine whether a statement holds true. For example, the brief phrase “The maximum is not guaranteed” does not tell readers what prevents it from being reached. A fuller explanation might identify an allocation limit as the constraint, but only if that condition has been verified for the system in question.
The examples in the materials illustrate writing techniques, not behavior shared across products. Statements about allocation limits, service updates, and execution limits need to be verified before reuse in another context.
The scope of editing also matters. A request to review wording calls for suggestions; a request to edit calls for changes to the specified document. Neither authorizes unrelated changes to other pages or skills. If saving or checking the rendered result is not possible, state that limitation.
Next Step#
Choose one unclear paragraph written by AI and ask for a revision using explain-before-shorten. Include one sentence specifying what readers need to understand.
Source: https://zenn.dev/microsoft/articles/explain-before-shorten
Contents
