# Technical Writing Prover MCP

> Technical Writing Prover validates AI-generated technical documentation against professional standards. It forces your agent to define the specific reader, structure the guide using Diátaxis principles, provide working code examples, eliminate ambiguity, and document all necessary prerequisites and error paths.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** technical-writing, documentation, diataxis, developer-docs, api-docs, code-examples, style-guide, content-quality

## Description

Look, we all know AI writes *pretty*. It sounds slick, like something you’d read on a corporate brochure—which means it's probably useless when an engineer actually tries to follow it. When your agent spits out documentation, it often reads like guesswork. That's not good enough for production code or anything that matters.

The `validate_technical_writing` tool fixes this mess. It doesn't just check grammar; it forces your AI client to prove the technical guide meets actual professional standards before you let anyone read it. When you run this, you're making sure the documentation isn't vague fluff—it’s actionable, complete code.

When you use `validate_technical_writing`, you get five critical checks built right in. First up, **defining the reader**. You can't just write for 'developers.' This tool demands that you define a specific target role—say, 'junior backend engineer'—and pin down their exact expertise level and all the prerequisites they need *before* it’ll even start validating content. It forces precision; no more writing ambiguous guides meant for everyone.

Next, **structure matters**. The output has to follow established documentation rules using Diátaxis principles. This means the structure can't be a random wall of text. You've got to classify it immediately: is this a tutorial? A quick how-to guide? Or deep reference material? It then enforces a clear, task-based hierarchy (H1 → H2 → H3) so you know exactly where you are and what steps you're taking.

Then there’s the code. The tool kills **pseudocode**. If it’s an example, it has to be runnable. It rejects anything that looks like theory; it demands complete, copy-pasteable code blocks. And here’s the kicker: for every block of code, you gotta specify the expected output and the exact runtime version it was tested against. You're not guessing; you're showing proof.

It also zeroes in on **ambiguity**. If your documentation uses passive voice—like 'it is recommended that...'—the tool flags it. It forces you to switch to active language, which means naming the actor doing the action and defining every single term immediately when you first use it. You'll never have to wonder who does what again.

Finally, no assumptions get through. The last step is verifying **completeness and error handling**. This doesn’t mean listing basic steps; it means documenting specific failure paths. If something breaks, the guide must say exactly what happens and how to fix it. You'll list prerequisites with version numbers attached, cover tricky edge cases, and map out every possible point of failure. It leaves nothing undocumented or assumed.

## Tools

### validate_technical_writing
Forces the agent to prove technical documentation meets professional standards by checking for defined audience, task-based structure, working examples, zero ambiguity, and verified completeness.

## Prompt Examples

**Prompt:** 
```
Write API documentation for the authentication endpoint. It should cover how to authenticate and include some examples.
```

**Response:** 
```
AUDIENCE_UNDEFINED — Who is reading this? A frontend developer integrating OAuth? A backend engineer implementing JWT validation? A DevOps engineer configuring API gateway auth? Each needs different content. Define: [ROLE: frontend engineer] → [EXPERTISE: mid-level, familiar with REST, new to OAuth 2.0] → [PREREQUISITES: HTTP basics, JSON, knows how to use curl] → [GOAL: authenticate a React SPA against this API and handle token refresh].
```

**Prompt:** 
```
Audience: mid-level backend engineers (2-5 years, familiar with Node.js and Express, new to this API). Goal: set up API key authentication for server-to-server calls. Structure: How-to guide (Diátaxis). H1: API Key Authentication. H2: Prerequisites → H2: Generate API Key → H2: Authenticate Requests → H2: Handle Errors → H2: Rate Limits → H2: Next Steps. Progressive: basic auth first, then scoped keys, then key rotation. Examples: curl command with real endpoint and expected 200 response, Node.js fetch with headers, error response for invalid key (401 with JSON body). All tested on Node.js 20 LTS. Clarity: zero passive voice, all terms defined on first use (API key, bearer token, rate limit), no 'it' without named antecedent. Completeness: prerequisites (Node.js 20+, npm 10+, API account), errors (401 invalid key, 403 insufficient scope, 429 rate limit with Retry-After header), edge cases (expired key, revoked key, concurrent key rotation), next steps: link to OAuth 2.0 guide and webhook setup.
```

**Response:** 
```
WRITING_PROVEN — Publication-ready technical documentation validated. Audience: mid-level backend engineers with Node.js prerequisite. Structure: Diátaxis how-to with progressive disclosure (basic → scoped → rotation). Examples: curl + Node.js fetch tested on Node 20 with expected responses. Clarity: active voice, terms defined, zero ambiguity. Completeness: prerequisites versioned, three error codes documented with headers, edge cases (expired/revoked/concurrent rotation), linked next steps. This doc reduces support tickets.
```

**Prompt:** 
```
Audience: junior DevOps engineers (0-2 years, familiar with Docker, new to Kubernetes). Goal: deploy first application to a K8s cluster. Structure: Tutorial (Diátaxis). H1→H2→H3 hierarchy with step-by-step progression. Examples: kubectl commands with expected output shown. All tested on K8s 1.30 / minikube. Clarity: active voice, terms defined (pod, deployment, service, namespace). But: no prerequisites section, no error handling ('if kubectl apply fails, do X'), no edge cases (what if namespace already exists, what if port is already bound), next steps say 'consult the Kubernetes documentation for more advanced topics.'
```

**Response:** 
```
COMPLETENESS_GAPS — Audience, structure, examples, and clarity pass. But completeness fails on three fronts: (1) No prerequisites — list kubectl version, minikube version, Docker version, and minimum system requirements. (2) No error handling — what if 'kubectl apply' fails? ImagePullBackOff? CrashLoopBackOff? Pending pod? Show the error, explain the cause, provide the fix. (3) 'Consult the Kubernetes documentation' is a completeness failure — link to the SPECIFIC next tutorial: 'Next: Expose your application with a Service (link).' Also: address edge cases — namespace already exists (409 Conflict), port already bound (address already in use).
```

## Capabilities

### Force specific reader definition
The tool requires you to define the documentation's target role (e.g., Data Scientist), expertise level, and required prerequisites before it will validate the content.

### Apply Diátaxis structure principles
It ensures the document has a clear, task-based hierarchy (H1→H2→H3) and properly classifies whether it's a tutorial, reference, or how-to guide.

### Validate working code examples
The tool rejects pseudocode, demanding complete, runnable code blocks with the expected output shown for a stated runtime version.

### Eliminate ambiguous language
It converts passive voice and vague terms into clear, active instructions by specifying the actor and defining all terminology on first use.

### Verify completeness and error handling
The tool mandates listing prerequisites with versions, documenting specific failure paths, and covering relevant edge cases.

## Use Cases

### Onboarding a new service client
A product manager needs to write onboarding docs for a complex API. Instead of writing vaguely, they run the draft through `validate_technical_writing`. The tool forces them to list prerequisites (e.g., Python 3.10+, specific OAuth scope) and structure the guide step-by-step, resulting in documentation that new users can actually follow.

### Updating legacy API endpoints
An engineer changes an old endpoint but writes vague notes: 'The config should be updated.' The Prover flags this as `AMBIGUITY_PRESENT`. The agent must rewrite it using active voice, specifying the exact configuration file and the actor responsible for the update.

### Creating deployment guides
A DevOps team drafts a K8s deployment guide. If they omit error handling (e.g., what happens when an image fails to pull), the Prover flags `COMPLETENESS_GAPS`. The agent is forced to add specific failure paths and recovery steps, making the guide safe for production.

### Documenting a complex workflow
A team needs to explain an end-to-end data pipeline. They use `validate_technical_writing` to ensure the document isn't just descriptive (a 'wall of text'). It forces them into a task-based structure, guiding the reader through the necessary steps in order.

## Benefits

- Stops guesswork: The tool forces you to define a specific reader role and expertise level, eliminating vague 'developers' language. You know exactly who the documentation speaks to.
- Guaranteed structure: It enforces Diátaxis classification (tutorial/how-to/reference), preventing your content from becoming an unusable wall of text. Every section has a defined purpose.
- Working code only: Forget pseudocode. The Prover demands complete, copy-pasteable examples with the expected output shown and tested on a specific runtime version.
- No more assumptions: By eliminating passive voice and requiring clear pronoun antecedents, you eliminate dangerous misinterpretations that lead to production errors.
- Full coverage: It mandates documenting prerequisites (with versions), error handling paths, and edge cases. Nothing slips through the cracks just because it was 'out of scope'.

## How It Works

The bottom line is you get a definitive pass/fail status and an actionable checklist that forces your agent to revise until the documentation meets professional standards.

1. Feed your AI-generated technical document draft into the agent.
2. Run the `validate_technical_writing` tool. It runs five checks: audience definition, structure, working examples, clarity, and completeness.
3. The output delivers a Verdict Matrix, showing which of the five pillars failed (e.g., `AMBIGUITY_PRESENT`), along with specific coaching notes on how to fix it.

## Frequently Asked Questions

**Does Technical Writing Prover only work with API documentation?**
No. While it's excellent for APIs, the tool validates any technical guide. It forces structure and clarity based on general principles (Diátaxis), whether you're documenting a deployment process or a data model.

**How many types of failure does validate_technical_writing catch?**
It catches five specific failures: undefined audience, absent structure, missing examples, ambiguity present, and completeness gaps. The tool's verdict matrix details each one.

**If I fix the errors manually, will Technical Writing Prover still validate it?**
Yes. You can feed your revised draft back into the agent and run `validate_technical_writing` again. It acts as a final quality gate to ensure you didn't just mask the original problem.

**Is Technical Writing Prover better than just using markdown headings?**
Markdown headings only help with organization; they don't prove correctness. The Prover forces *content* quality by demanding active voice, tested code blocks, and error handling paths.

**How thoroughly does validate_technical_writing check complex error handling and failure paths?**
It verifies that you document every potential failure path. You must show the expected error code, explain what caused it (e.g., 403 vs. 429), and provide the actionable fix or retry logic. Simply stating 'check documentation' isn't enough; we need specific steps for common failures like `ImagePullBackOff`.

**Does Technical Writing Prover help document rate limits and backoff strategies?**
Yes, it enforces the inclusion of operational limitations. When documenting API access, you must specify the rate limit (e.g., 100 calls per minute) and detail the required retry strategy, like exponential backoff. This moves documentation beyond just 'it works.'

**What source materials can I use when calling validate_technical_writing?**
You can provide plain text or markdown formatted documentation drafts. The tool doesn't care about the input format, but it absolutely needs enough context for us to analyze it. Don't just send bullet points; give us paragraphs that mimic real technical writing.

**Does Technical Writing Prover verify best practices for authentication and security documentation?**
It checks if the *process* of secure authentication is documented, not if your code is secure. You must actively define how to handle credentials, document token rotation procedures, and state prerequisites like required client IDs or scopes. Vague language fails here.

**Does it write documentation?**
No. It validates that documentation meets five quality standards — defined audience, task-based structure, working examples, eliminated ambiguity, and verified completeness. It does not generate text. It forces you to prove your text is publication-ready.

**What is the Diátaxis framework?**
Diátaxis classifies documentation into four types based on reader need: tutorials (learning-oriented, guided steps), how-to guides (task-oriented, goal-focused), reference (information-oriented, API specs), and explanation (understanding-oriented, conceptual). Each type has different structural requirements. Mixing them produces documentation that serves none well.

**Can it validate non-code documentation like architecture decision records?**
Yes. For conceptual documents (ADRs, RFCs, design docs), the examplesWorking pivot applies to illustrative diagrams, data flow descriptions, or before/after comparisons instead of code blocks. The tool adapts to the document type — but the other four pivots (audience, structure, ambiguity, completeness) apply to every technical document regardless of type.