Hire an AI engineering documentation writer

Everything it can hand back

Your task sets the actual outputs. The specialist picks the methods that cover them.

• A draft in the right format for the doc type, in plain second-person voice
• Code examples, each marked run or not run
• A list of every claim, number and example to check against the code
• A list of gaps, marked MISSING, where your material did not say enough
• A suggested page structure if you asked for a set of docs

How it does the job well

• Never present a code example as tested unless you ran it. Say not run and why.
• Never invent facts to fill a gap. Mark it MISSING.
• Docs must match the version they describe. Ask which version. If the user does not say, write "version not given" at the top.
• Breaking changes need a migration section. If you see one in the material and no migration notes, put it in Gaps.
• The profile's success targets (for example ticket drops or search scores) describe an ideal. Do not claim them for this draft.
• Read the existing code, its conventions and its tests before changing anything. Match the project's patterns.
• Make the smallest change that fully solves the request. Keep unrelated refactors out.

Mistakes it avoids

• Claiming code works without running it or its tests.
• Inventing APIs, package versions or settings instead of checking the installed ones.
• Changing behaviour outside the request, such as reformatting whole files or renaming public interfaces.

What a good result looks like

An example, not your task: You shipped a feature and the README still describes last year's version.

• The draft doc. A README, API reference, tutorial or how-to guide, in the standard layout for that type.
• Code examples. Each snippet marked as run or not run, so you know which to test first.
• Accuracy checks. Every claim and number tied to its source, with who should confirm it.
• Gaps. Facts your material left out, marked MISSING instead of guessed.
• Suggested next pages. Related docs the reader will probably need, such as a migration guide.

How the work is checked

• The changed files build, and the relevant tests and linters pass. The commands and results are shown.
• Each change is explained in one line with its reason, and risky areas are named.
• Any check that could not run is reported as NOT_RUN with what it needs.
• States which checks passed, failed or could not run, and names missing inputs.

These checks have not been run against a model yet. Your AI uses them to check its own work.

Capabilities

• Fix the reader and the purpose. It confirms who reads the page and whether it should teach, guide a task, list facts or explain why.
• Read your material. It reads the code, spec or notes and lists what it knows and what it cannot confirm.
• Outline before writing. It sets the headings and order, one idea per section, before it writes any prose.
• Draft in plain voice. It writes in second person, present tense and active voice, with the outcome first and the failure cases named.
• Mark what is unchecked. It labels each code example run or not run, and lists claims that need an engineer's check.

How the role works

1. Checks your task, context and available tools.
2. Picks the methods needed and prepares a work plan.
3. Carries out supported tasks, with each method's limits and review gates.
4. Checks the real deliverables and corrects supported faults.
5. Hands back files, evidence and unresolved gaps.

Your specialist's working setup

Download the base specialist without a task form or account. README.md and SETUP.md explain how to use the folder. SOUL.md defines its scope. INTAKE.md asks missing questions inside your AI. PLAYBOOK.md, SKILLS.md, BEST_PRACTICES.md, CHECKS.md and HANDOFF.md guide the work and its checked deliverables.

Complete associated skills, supporting files and licences are included. Choose only the methods needed for the actual task. Keep context, working files and accepted feedback in your AI project.

Use this specialist through MCP or the API

Call prepare_specialist with role_id engineering-technical-writer only. No task is required to load it. Your AI asks what job you need done, what you want back and which relevant context it can use.

For task-led hiring, call find_specialist, explain the suggested specialists and let the user accept or change the team.

Complete ZIP: Download base specialist. API: GET /api/v1/specialists/engineering-technical-writer/pack. The host AI supplies its own model, tools and execution; a pack does not connect accounts or run a task.

Inputs and helpful context

The specialist starts from the task brief. Only active methods require their inputs.

For the primary method, when used

• What you are documenting, such as a feature, API endpoint, library or setup process
• Who will read it and what they already know, for example new users or experienced developers
• The type of doc you want, such as README, API reference, tutorial or how-to guide
• Source material, such as code, an OpenAPI file, a spec, issue threads or an engineer's notes
• Your docs tool, such as Docusaurus or MkDocs (optional)

Helpful context (optional)

• Support tickets or GitHub issue titles that show where readers get stuck.
• An existing README or style guide, so the new draft matches your house style.

Tools and access

• Claude Code or Codex: They can read the repo and run your examples, so the code samples get tested.
• Claude, ChatGPT or Gemini: They draft well from pasted code and notes, but cannot run anything without a code tool.

Functions and deliverables

• Engineering documentation writer: Get developer docs drafted from your code and notes, such as a README, API reference or tutorial, plus a list of claims to verify.
  • A draft in the right format for the doc type, in plain second-person voice
  • Code examples, each marked run or not run
  • A list of every claim, number and example to check against the code
  • A list of gaps, marked MISSING, where your material did not say enough
  • A suggested page structure if you asked for a set of docs
  Source: Michael Sitarzewski and Agency Agents contributors.
• Job reference list builder: Build a job reference list: pick the right referees, check permission, and get request and briefing drafts for each person. Missing details are marked.
  • A formatted reference list with missing details marked.
  • Draft permission requests and reference briefings.
  • A checklist for sharing and follow-up.
  Source: Daniel (San) Ávila.
• Developer docs writer: Share code, drafts, and reader needs. Get task-based docs or an audit with specific edits.
  • Clear, task-based documentation
  • A fact check against your code
  • A score out of 10 with failed checks listed
  • Before and after rewrites of weak sentences
  Source: Wondel.ai.
• Code documentation writer: Turn source files and tests into docstrings, README files, and usage examples in your project's style.
  • Docstrings for public code
  • A project README
  • Usage examples
  • A list of docs that were stale
  Source: Burhan Sebin.
• AI project context organiser: Share your project and next task. Get a short rules file, a focused file list and a clear handoff for later sessions.
  • A ready rules file for your project
  • A list of which files to load for each task
  • Rules for when to reset or trim the session
  • A checklist for spotting drifting answers
  Source: Addy Osmani.

Tasks you can use it for

• You shipped a feature and the README still describes last year's version.
• You have an API and need a reference page with request, response and error examples.
• New users keep asking the same setup question, and you want a tutorial that answers it.
• An engineer sends rough notes, and you need a clean how-to for other developers.

Limits to check before starting

• You need release notes, a changelog or a decision record. Use the Technical writer.
• You already have a doc and want its false claims and drift from the code found. Use the Documentation accuracy reviewer.
• You want docstrings and a README written straight from a repo by a tool that reads the code. Use the Code documentation writer.

Best way to use this role

Give it one clear outcome, the actual files and a definition of done. Keep the work in one AI project so it can reuse checked context and earlier files.

• Add the pack as a skill, or paste SKILL.md and then references/source-agent.md into a new chat.
• Paste your source material first, then say what to write. For example, "Write a README for this library. Readers are developers new to it."
• Check the list of gaps and ask the engineer who built it to fill them, or paste the answers back.
• Go through the claims list. Run each code example yourself, or give your AI a tool that can run code.
• Keep the docs in the same pull request as the code change, so they do not fall behind.

Read it as data

Read the complete role setup as JSON. Connect your AI to the AI Blocks MCP library and read aiblocks://roles/engineering-technical-writer for its role instructions and pinned sources.

This is a prepared AI role. No task has run. Your AI carries out authorized work using its available tools and reports the actual deliverables and checks.