# Reverse authoring: write the text first, mark it up last

Most authors start with `{a|b|c}` fragments, hoping a stack of synonyms adds up to an article. That approach falls apart the moment grammar, tenant-specific facts, or real narrative flow get involved. The fix is a simple shift in direction.

## The mental model

The parser and the author work in **opposite directions**.

-   The parser expands syntax from the inside out. Inner enumerations resolve first, then outer ones, then permutations, then variable substitution.
-   The author designs the template from the _resolved_ readable phrase _back_ into syntax.

You are not generating variants. You are constraining one clean article into something the engine can safely regenerate a thousand times without breaking grammar.

That is the whole shift:

```
final readable phrase
→ bind grammar
→ choose safe branch boundaries
→ extract variables
→ add structural variation
→ add local synonyms last
```

Synonymization is the last refinement, not the first step.

### Use this guide as an AI prompt

You can read this page as a human author, or you can feed it to Claude, GPT, or Gemini as a prompt. That is the whole premise of Spintax: **write one template with AI, render it safely and cheaply forever.**

**How to use it that way:**

1.  Paste this whole guide into your chat.
2.  Below it, paste your draft article.
3.  Ask: _"Convert my article into a spintax template. Follow the rules above. Readability wins over variety."_

Every rule below is phrased so that a model can apply it directly. The anti-patterns list doubles as a checklist for the model to self-review its output.

Working through an agent instead of a chat window? Everything here is machine-ready: this page as clean Markdown at [/docs/authoring-mindset.md](https://spintax.net/docs/authoring-mindset.md), the whole series condensed into the [spintax-authoring skill](https://spintax.net/.well-known/agent-skills/spintax-authoring/SKILL.md), and an MCP server at `https://spintax.net/mcp` whose `validate_spintax` tool lets the model check its own template before you ever see it. The full setup, with a ready prompt, is in [writing spintax templates with AI](https://spintax.net/ai-spintax-templates.md).

## The five-step reverse workflow

1.  **Write the final sentence in plain language.** No curly braces, no square brackets, no variables. Just the sentence you want a reader to see.
2.  **Mark grammar that must stay bound.** Subject + verb. Preposition + object. Article + noun phrase. Noun + adjective agreement. These cannot be split by a branch boundary.
3.  **Choose safe branch boundaries.** A branch boundary goes _between_ grammatical units, never inside one.
4.  **Extract repeated or tenant-specific facts into variables.** Anything that changes per site, per product, or per article moves to `%VariableName%`.
5.  **Add structural variation first, local synonyms last.** Permutations and optional fragments create real variety. Synonyms are a small, final refinement inside already-safe grammar slots.

The practical test before every `{a|b}` you write:

> _If I swap only this fragment, do case, agreement, governance, articles, and word order all remain correct?_

If the answer is not an immediate yes, bind a larger phrase in one branch.

## Phase 0 — Write a readable article first

The source text is an article first and a spintax input second. Readability always wins over template convenience.

### Step 1. Write a normal article

Write a clean, readable article as if no templatization will happen. Include introductions, transitions, context, explanations — everything a good article needs. Your voice. Your hooks. Real flow between sections.

Do not optimize for spintax at this stage. You are writing for one human reader. The template comes after.

### Step 2. Identify templatizable zones

Not every paragraph needs to be variable. Walk through the finished text and mark specific zones that are good candidates:

-   **Factual lists** (features, use cases, supported integrations) — items can shuffle and subset.
-   **Parallel descriptions** (product tiers, platform capabilities) — items with similar structure can reorder.
-   **Opening sentences of sections** — usually can have two or three alternative phrasings.
-   **Concrete data points that vary by tenant** — become variables.

Leave the rest as-is. Intros, transitions, explanatory text, and narrative flow usually read better fixed. Templatizing them adds complexity with little real anti-footprint value.

A typical article ends up roughly **60-70% fixed readable text and 30-40% templatizable zones**. That ratio is the sign of a healthy template.

### Step 3. Prepare templatizable zones

Inside the marked zones only, apply these writing principles:

-   **Sentence independence.** Each sentence in a permutable zone should stand alone. No "This is why...", "Therefore...", or "As mentioned above..." — those break when sentences are reordered.
-   **Parallel list items.** Items that will be permuted should follow the same grammatical pattern — same structure, same sentence shape. Parallel items are interchangeable, which is exactly what permutations need.
-   **One idea per sentence.** Separate ideas into individual sentences. Each becomes a permutation element.
-   **Concrete over vague.** Specific facts produce better variation than generic adjectives. "Requests complete in under 100 ms" gives more to work with than "It is fast."

## General article rules

These apply everywhere in the article, not just inside templatizable zones.

-   **Brand placement.** Mention the brand early, then use generic references ("the platform", "the product"). The whole article should read naturally without the brand name in every paragraph.
-   **Avoid stale instructions.** Do not write step-by-step walkthroughs for third-party UIs (wallets, dashboards, external integrations). They change frequently and your template goes stale. Describe what the tool does in one or two sentences instead.
-   **Section length.** `<h2>` sections: 100–250 words. `<h3>` sections: 50–150 words. If a section crosses ~300 words, split it.
-   **No filler or meta-commentary.** Remove sentences that talk about the text instead of conveying information: "Let's take a look at...", "It is worth noting that...", "This section will explain..."

## Common mistakes at the authoring stage

| Don't | Why | Do instead |
| --- | --- | --- |
| Start with `{a|b|c}` fragments | You're solving the syntax puzzle before the content exists. | Write a normal article first. Add syntax last. |
| Templatize every paragraph | Destroys readability without adding variety. | Templatize ~30–40% of zones. Leave narrative fixed. |
| Permute narrative sentences | "As we saw above..." breaks when order changes. | Keep narrative fixed. Only permute independent facts. |
| Write synonyms before structure | You lock grammar before thinking about shape. | Structure first (permutations, variables), synonyms last. |
| Pack three ideas into one sentence, then try to permute | Elements overlap and reordering produces nonsense. | One idea per sentence inside permutable zones. |

## Source-text checklist

Before moving on to markup, verify:

-   The article reads well as a standalone page.
-   Templatizable zones are identified — not the whole text.
-   Sentences inside those zones stand alone.
-   List items inside those zones are parallel.
-   Brand is mentioned sparingly.
-   No step-by-step instructions for third-party UIs.
-   No filler or meta-commentary.
-   Each `<h2>` and `<h3>` section is within length limits.

If every box is ticked, the source text is ready. The next three guides turn that source into a template: variables, permutations, and grammar-safe synonymization — in that order.

---

## Continue the series

- [Variables & multi-site reuse](https://spintax.net/docs/variables.md): Precedence, reroll gotchas, separator collisions.

- [Permutations in practice](https://spintax.net/docs/permutations.md): Lists, title-style headings, separator rules.

- [Grammar-safe synonymization](https://spintax.net/docs/grammar-safe-spintax.md): Binding rules. English agreement. Plus Russian cases in the RU version.

- [Template composition](https://spintax.net/docs/template-composition.md): Variables as rendered HTML chunks. Item → section → orchestrator pipeline.

- [Conditional spintax](https://spintax.net/docs/conditional-spintax.md): Value-driven {?VAR?then|else} — the syntax-level alternative to random enum picks.

- [Plural agreement](https://spintax.net/docs/plural-spintax.md): Pick the right noun form by count. RU/UK/BE and SR/HR/BS 3-form, EN-style 2-form.

- [Spintax by example](https://spintax.net/examples.md): Every technique in the series, applied to one real paragraph, with real renders.

[Open in playground](https://spintax.net/play/) [Back to all guides](https://spintax.net/docs.md)

---

Source: https://spintax.net/docs/authoring-mindset/