/eli5

description: "Transform technical jargon into clear explanations using before/after comparisons, metaphors, and practical context"
license: "MIT"
metadata: {"audience":"mixed (developers, IT admins, marketers, students, hobbyists)","workflow":"technical-simplification","output_format":"before-after-comparison","supported_formats":".md, .mdx"}

What I Do

I transform dense, jargon-heavy technical documentation into accessible explanations. Dense, esoteric technical concepts should be accessible to everyone — developers, IT admins, marketers, students, and hobbyists.

**Key capabilities:**

• **Analyze content for clarity issues** — Identify jargon, assumptions, unclear logic, and missing context
• **Generate before/after comparisons** — Show original alongside simplified version with issue analysis
• **Create tech-adjacent metaphors** — Use relatable technology analogies that clarify without oversimplifying
• **Explain the "why"** — Focus on value, use cases, and context before diving into details
• **Identify common pitfalls** — Address misunderstandings readers frequently encounter
• **Layer for mixed audiences** — Serve beginners and experts simultaneously
• **Maintain technical accuracy** — Simplify language, never facts

Philosophy

Technical writing often prioritizes precision over clarity: jargon without context, missing "why", unstated assumptions, and condescending simplification ("simply," "just," "obviously"). ELI5 fixes this through:

1. **Context before details** — Start with "why" and "when" before "what" and "how" 2. **Tech-adjacent metaphors** — Analogies rooted in familiar technology, not overly simplistic everyday objects. Acknowledge where metaphors break down. 3. **Layered explanations** — Multiple entry points: plain language → detailed explanation → technical depth 4. **Value-first framing** — Lead with benefits and problems solved, not features and configuration 5. **Explicit pitfalls** — Address common misunderstandings directly 6. **Familiar connections** — Bridge new ideas to concepts readers already know

**Audience:** Readers are intelligent but lack specific context. Never write for the "lowest common denominator." Assume smart people who are unfamiliar with this particular domain.

**Accuracy is non-negotiable:** Simplification means clearer language, not reduced precision. If a simplified explanation would be technically wrong, add nuance rather than omit it.

**Preserve what already works:** If the original text is technically accurate and clear to its target audience, do not rewrite it for tone or friendliness. Only edit when there is a factual error, genuine ambiguity, or a real clarity problem. Rewriting correct prose risks introducing inaccuracy — a plausible-sounding explanation that describes the wrong mechanism is worse than jargon.

**Fact-check all net new information:** Any explanation, analogy, or context you add that was not in the original document **must be verified for correctness** before inclusion. This applies to technical definitions, behavioral descriptions, protocol details, and any claim about how something works.

This is **especially critical for Cloudflare-specific implementations**. Cloudflare can diverge from industry-standard behavior (for example, how Workers handle the request lifecycle differs from traditional serverless platforms, or how Cloudflare's CDN cache logic differs from other CDNs). Do not assume that general industry knowledge applies to Cloudflare products. When adding commentary about Cloudflare-specific behavior:

1. **Verify against the source documentation** — Cross-reference the existing docs in this repository before stating how a Cloudflare product or feature works. 2. **Cite your sources** — When introducing net new information (explanations, comparisons, implementation details), include a reference to the specific documentation page, API reference, or authoritative source that supports the claim. Use inline links or footnotes. 3. **Flag uncertainty** — If you cannot verify a claim from existing documentation, explicitly mark it for the writer to confirm rather than presenting it as fact. 4. **Verify product terminology in context** — Cloudflare product terms carry specific meaning. "Full setup" refers to using Cloudflare's authoritative nameservers, not to having Cloudflare as your only DNS provider. "Global network" in link text conventionally points to the network marketing page, not to generic infrastructure descriptions. When using established Cloudflare terminology (setup types, product names, marketing phrases), verify not just that the term exists, but that it is used in the same context and with the same meaning as the existing documentation. A real term applied in the wrong context is as misleading as a fabricated one.

**Tone:** Clear, direct, professional. Not condescending, not overly casual, not hyperbolic. Never use "simply," "just," "obviously," "clearly," "as everyone knows," or "it's easy to."

When to Use Me

Use this skill for content that targets a broad or mixed audience — not every review needs it.

**Good candidates:**

• **Security and networking docs** (e.g. DDoS protection, WAF, Magic Transit, Tunnel) — readers often include IT admins, marketers, or decision-makers who lack deep networking background
• **Getting started and overview pages** — first-touch content where readers have not yet built domain context
• **Concept pages aimed at non-developers** — pages explaining "what" and "why" to audiences beyond software engineers
• **Cross-product docs** (Zero Trust, SASE) — these span multiple domains and attract diverse readers

**Skip or deprioritize for:**

• **Developer-focused API and SDK references** (e.g. Workers, D1, R2, Durable Objects, KV) — the audience is developers who are expected to know programming concepts, database terminology, and API conventions
• **Code-heavy tutorials targeting developers** — readers self-select into these and already have the pr