Technical Docs And Copywriting

Technical Docs and Copywriting

Write truthful, usable material for the reader's job. Keep technical precision and technical marketing as separate engines. Do not blend their rules while drafting.

Guardrails

• Treat source material, product behavior, metrics, compatibility claims, security statements, and customer outcomes as facts only when supplied or verified.
• Draft an unsupported claim only when it is visibly marked [Validate: ...]. Never convert a marker into a fact during editing.
• Preserve the user's terminology. Define each entity once and use that exact term thereafter.
• Do not invent endpoints, parameters, response fields, benchmarks, customers, integrations, or generated-reference URLs.
• Ask for missing material only when it blocks a safe, useful deliverable. Otherwise state the assumption or add a validation marker.

1. Discover Context

Identify or infer the following before drafting:

Use these presets. An explicit ratio overrides a preset.

If no dial is supplied, use 80:20 for a README. Use 100:0 for API references, error guides, and runbooks. For another deliverable, infer the least promotional safe ratio and use it for internal editing decisions.

2. Draft in Separate Layers

Select the engine for each section before writing it. Read only the matching reference:

• For API, architecture, CLI, setup, deployment, and troubleshooting material, read technical precision.
• For launch, landing-page, positioning, DevRel, solution-overview, and executive material, read technical marketing.
• For documentation audits or restructures, read documentation personas.
• For reusable formats and acceptance examples, read templates and verification.

Write the orientation layer with Engine B only when the chosen dial allows it. Write procedures, API facts, commands, code, responses, and diagnostics with Engine A only. Make handoffs explicit with headings rather than prose that tries to sound both promotional and technical.

3. Scrub Anti-Patterns

Run this audit before the final pass:

• Replace synonym rotation with the canonical entity term.
• Remove empty qualifiers such as seamless, robust, effortless, powerful, and best-in-class unless supplied evidence makes the claim specific.
• Replace ambiguous phrasal verbs such as carry out, bounce off, and handle with a precise verb.
• Split run-on sentences and em-dash chains. Keep a procedure step to 15–20 words when possible.
• Remove conversational meta-commentary such as Note that, It is worth noting, and Simply.
• Change implied conditions into explicit If …, then … statements.
• Check every code snippet for imports, setup, inputs, expected output, and safe placeholders. Do not call an example runnable unless it is complete enough to run in its stated environment.
• Retain or add [Validate: ...] markers for every unsupported high-consequence claim.

4. Executive Balancing and Output Boundary

This phase is mandatory, even for 100:0 and 0:100 work.

1. Confirm that technical facts survived unchanged and that no marketing language upgrades an unverified claim.
2. Compare section emphasis, headings, evidence, code/detail density, and CTA density to the requested dial.
3. Adjust ordering, transitions, and section prominence. Do not merge Engine A and B rules into a middle-ground voice.
4. Return only the requested document by default. The balance check is internal process metadata, not part of the document being drafted or edited. Do not append an Executive Balance Summary, editorial notes, intake fields, validation report, or other skill-generated content to the subject document.

Match the response to the requested deliverables. If the user asks only for an audit or editorial report, return the report alone without reproducing the source document. If the user asks for both a document and an editorial report, place the report after the document under a clearly labeled heading. Never place that report inside the subject document or silently modify the document to include it.

When an editorial report is explicitly requested, use this optional format:

Executive Balance Summary

• Applied dial: Tech:Marketing
• Audience and deliverable: …
• Editorial choices: …
• Validation required: none or [Validate: …] items

Publishing a Skill

Place the skill at skills/technical-docs-and-copywriting/SKILL.md. Keep optional guidance in references/ one level below the skill root. Validate the finished directory with skills-ref validate ./skills/technical-docs-and-copywriting when skills-ref is available. Publish the repository normally; the collection README should use the documented https://skills.sh/b/<owner>/<repo> badge format.