Write an explainer
- name
- explainer
- description
- Help a person choose and write the best explainer for what they need to explain on a Bloggo blog, from scrollytelling to annotated walkthroughs to a plain post with helpful extras. Use first when asked for an explainer, a visual or interactive post, a "how it works" page, or to make a hard topic easy to follow.
- compatibility
- The block formats need the explainers feature on the blog (GET /v1/features lists it). Without it, write an ordinary post and use the structure skills only.
Explainers
An explainer is a post whose job is to make one thing understandable. Two choices decide its quality: what shape the content takes (a format) and how the argument is ordered (a structure). This skill helps you make both choices, then hands you to the right skill. Setup, keys and publishing are in the Bloggo skill.
1. Ask before writing
Ask the person at most four things, in one message, and do not start before you have answers:
- Who is the reader, and what should they understand or be able to do afterwards?
- What is the one thing to explain? If it is two things, plan two explainers.
- What visuals exist (images, screenshots, charts, code, a diagram)? You can write diagrams yourself as text, so "none" is fine for processes and systems.
- How long should it take to read: two minutes, ten?
If the person already gave notes or a draft, read them and ask only what is missing.
2. Pick the format
| The reader needs to... | Format | Skill |
|---|---|---|
| Follow a story or a change over time while a picture, map, chart or code changes beside the text | Scrollytelling | explainer-scrollytelling |
| Understand how one thing is built or works, part by part, on a diagram, screenshot or code listing | Annotated walkthrough | explainer-annotated-walkthrough |
| Read mostly prose that needs help: definitions, side notes, a timeline, key takeaways, before and after | Page furniture | explainer-page-furniture |
| Just read an argument or a story | An ordinary post | write-post-from-notes |
When two fit, prefer the simpler one. Choose scrollytelling only with three to eight visuals (or visual states) that really differ. Choose an ordinary post when no visual would teach anything the words do not. Page furniture can be added to any of the others. Math and code appear in all kinds of posts: see math-and-code-blocks.
3. Pick the structure
The structure is the order of the ideas, and it matters more than the format. Pick one and follow it.
| The explainer is mainly... | Structure | Skill |
|---|---|---|
| Making a case or a recommendation to busy people | Situation, Complication, Resolution | explainer-structure-scr |
| Reporting a result or a decision people will act on | Answer first (pyramid, bottom line up front) | explainer-structure-answer-first |
| Telling how something happened, with tension | And, But, Therefore | explainer-structure-abt |
| Teaching a concept to readers at different levels | Layered: simple, then deeper | explainer-structure-layered |
| Showing a process, a mechanism or a comparison | How it works | explainer-structure-how-it-works |
Good pairings: scrollytelling with And, But, Therefore or How it works; walkthroughs with How it works or Layered; page furniture with Layered or Answer first. Situation, Complication, Resolution suits the opening of any of them. If unsure, use Layered for teaching and Answer first for deciding.
4. Work in this order
- Say in one sentence what the reader will understand. If you cannot, ask again.
- Read the format skill and the structure skill you chose.
- Outline in the structure's terms and show the outline to the person when the post is long. Change the outline, not the finished text.
- Check
GET /v1/featureslistsexplainersas enabled for the blog; if it does not, tell the person and write an ordinary post. Then write as a draft:POST /postswith the Markdown, thenGET /posts/:id/previewand check the result, including the blocks. - Fix what the preview or the save notes report. Tell the person what you made and where to see it.
- Publish only when asked.
Rules for every explainer
- Every image has alt text that says what it shows and why it matters, not "image".
- The text must still make sense with every visual removed. Feeds and the raw
.mdshow the text without them. - One idea per paragraph or step. A step has at most about 60 words.
- Define a term the first time it appears, or use a page furniture definition.
- Put the most important sentence where a skimmer will see it: the summary, the first paragraph, or a takeaways box.
- Use only the block syntax these skills describe. Raw HTML is shown as text, and CSS or JavaScript cannot be added.
- Do not invent facts, numbers or sources to make a story neater. Mark guesses as guesses.
When something fails
A block with a mistake is drawn as its plain content, and the reply of the save carries notes that name the block and the problem (they start with "Explainer block:"). Fix that block and save again. A blog without the explainers feature draws every block as plain content and gets no notes: a callout becomes ordinary paragraphs, a walkthrough becomes a figure with a numbered list, scrollytelling becomes its pictures and paragraphs one after the other. Write the text so that is still fine.