Case Study 02: Raj's Technical Documentation Prompt — Precision Under Pressure

Chapter: 7 — Prompting Fundamentals: Structure, Clarity, and Specificity Persona: Raj (Senior Software Engineer, Mid-Sized SaaS Company) Scenario: Building a prompt that produces dual-audience API documentation — one version for developers, one for non-technical stakeholders — without running two separate AI sessions

Background

Raj's company has just completed a major upgrade to their payment processing API. The new version handles multi-currency transactions, includes improved error codes, and has a new webhook architecture for real-time payment status updates. The old documentation is outdated, and they need to ship the new docs alongside the product release in 72 hours.

There are two documents to produce:

Technical API Reference — for developers integrating the API. Needs endpoint specifications, request/response schemas, error code definitions, authentication details, and code examples.
Executive Summary of API Changes — for the product leadership team and two enterprise clients' CTOs who need to understand what changed, why, and what the migration path looks like, without needing to read technical specifications.

Raj has used AI tools for code generation and debugging for about a year, but has less experience using them for documentation. His first instinct is to prompt for each document separately with straightforward instructions. This case study shows why that approach produced mediocre results — and how applying the principles from Chapter 7 transformed the outcome.

Attempt 1: Raj's First-Instinct Approach (Two Separate Prompts)

Prompt 1A (Technical Documentation)

Write API documentation for our new payment processing API. It has endpoints for
creating payments, getting payment status, refunds, and webhooks. Include code
examples.

Prompt 1B (Executive Summary)

Write an executive summary of our new payment API for non-technical stakeholders.

The Outputs

Technical output problems: - The AI generated generic REST API documentation with placeholder endpoints like /api/payments — not the actual endpoint paths - Code examples were in Python, but Raj's team uses Node.js - The authentication section described bearer tokens generically without reference to the company's specific API key format - Error codes were invented (the AI generated plausible-sounding but entirely fictional error codes) - The webhook architecture section was one paragraph — far too thin for a technical audience who needs to implement against it

Executive summary problems: - The output was written as if the API was being launched for the first time, not upgraded - It contained technical terms (REST, JSON, webhook) without defining them - It did not address the migration from old to new — which is the only thing the CTOs actually care about - It ended with a vague statement about "modern API best practices" that communicated nothing

Root causes: Both prompts suffered from the same core problem: Raj provided the AI with a task but almost no context. The AI generated technically competent generic API documentation and a technically competent generic executive summary — neither of which was useful because neither of them was about Raj's actual API.

Attempt 2: Adding Context — Improvement With Remaining Gaps

After recognizing the problem, Raj took a different approach. He compiled the actual technical details of the API into a reference summary (a 300-word internal specification document) and used it as context.

The Prompt (combined, with pasted context)

I am documenting a payment processing API upgrade. Here is the technical summary
of what is changing:

[Raj pastes 300-word technical specification document here]

Please produce two documents:

1. Technical documentation for the development team implementing the API
2. An executive summary for non-technical stakeholders (product leadership and
   two enterprise client CTOs)

Analysis of Improvement

The output was substantially better. The endpoints were now correct. The language matched the actual system. The executive summary addressed migration.

Remaining problems:

The two documents were not sufficiently differentiated in depth or tone. The technical document was accurate but lacked the structure a developer needs for implementation (specifically: no authentication section, no error code table, no webhook payload examples).
The executive summary still used technical terms without translation.
There was no format specification, so both documents were presented as running prose — not the format appropriate for either use case.
The code examples were still absent from the technical document because Raj had not specified a language.

The problem was that Raj added context but not format or constraints. Half the components were now present; half were still missing.

Attempt 3: The Fully Specified, High-Performance Prompt

Raj invested 20 minutes building the final version of this prompt. He drew on his actual API specification, his knowledge of the two audiences, and the formatting requirements for each document type.

The Prompt (full text)

I need two documentation documents for our payment processing API v2.0 release.
These need to be production-quality — one will be shipped to developers, one will
be shared with executive stakeholders and two enterprise client CTOs.

--- TECHNICAL CONTEXT (paste into your reference for both documents) ---

Upgraded API: Meridian Payments API v2.0
Base URL: https://api.meridianpay.com/v2
Authentication: API key in Authorization header as "Bearer {api_key}"
New capabilities vs v1: Multi-currency support (28 currencies), improved error
taxonomy (from 12 generic codes to 47 specific codes), real-time webhook
architecture replacing polling model.

Endpoints:
- POST /payments — Create a payment (new: currency field required)
- GET /payments/{id} — Get payment status (new: returns currency and exchange_rate)
- POST /payments/{id}/refund — Create refund (new: partial refund support)
- POST /webhooks — Register webhook endpoint (new in v2)
- DELETE /webhooks/{id} — Remove webhook (new in v2)

Webhook events: payment.completed, payment.failed, payment.refunded
Webhook payload includes: event_type, payment_id, amount, currency, timestamp,
idempotency_key

Key error codes: 4001 (invalid currency), 4002 (insufficient funds),
4003 (card_declined), 4010 (duplicate_idempotency_key), 5001 (webhook_unreachable)

Breaking changes from v1: currency field now required in POST /payments;
polling endpoint /payments/{id}/status deprecated (use webhooks); old error code
format ("error": "generic_failure") replaced with structured codes.

Migration path: v1 endpoints supported through December 31; recommend parallel
testing period of 2 weeks.

--- END TECHNICAL CONTEXT ---

DOCUMENT 1: TECHNICAL API REFERENCE

Audience: Developers integrating the Meridian Payments API. Assume strong
familiarity with REST APIs, JSON, and HTTP. Some may be new to webhook
architecture.

Format:
- Section 1: Authentication (how to format the API key, example request header)
- Section 2: Endpoints — for each endpoint: method + path, description, request
  parameters (table: name, type, required, description), example request (Node.js),
  example response (JSON)
- Section 3: Error Codes — table with code, name, description, recommended action
  (only include the 5 provided above)
- Section 4: Webhooks — how to register, payload structure, event types,
  retry logic note
- Section 5: Migration from v1 — 3-5 bullet summary of breaking changes and
  migration steps

Use code blocks for all examples. Use tables for parameters and error codes.
No prose padding — this is a reference document.

---

DOCUMENT 2: EXECUTIVE SUMMARY OF API v2.0 CHANGES

Audience: Three non-technical readers: our VP of Product, and two enterprise
client CTOs who evaluate vendor API changes from a business/risk perspective.
No code. No HTTP terminology. No acronyms without definition.

This document should answer exactly three questions these stakeholders actually care
about:
1. What changed and why? (benefits, not features)
2. Is there any risk to our existing integration during the transition? (be honest
   about the migration requirement)
3. What do we need to do and by when? (action items with dates)

Format: Three sections matching the three questions above. Maximum 400 words total.
Tone: Confident, clear, reassuring without minimizing real migration requirements.
No jargon. No passive voice.

The Outputs

Technical API Reference (condensed excerpt shown):

Meridian Payments API v2.0 — Technical Reference

Authentication

All requests to the Meridian Payments API must include your API key as a Bearer token in the Authorization header.

Example request header: Authorization: Bearer mp_live_4xKj9mNq2rWzT8vP

Endpoints

POST /payments

Create a payment

Parameter Type Required Description

amount integer Yes Amount in smallest currency unit (e.g., cents)

currency string Yes ISO 4217 currency code (e.g., "USD", "EUR") — new in v2

customer_id string Yes Customer identifier

idempotency_key string Recommended Unique key to prevent duplicate charges

Example request (Node.js): javascript const response = await fetch('https://api.meridianpay.com/v2/payments', { method: 'POST', headers: { 'Authorization': 'Bearer mp_live_4xKj9mNq2rWzT8vP', 'Content-Type': 'application/json' }, body: JSON.stringify({ amount: 4999, currency: 'USD', customer_id: 'cust_8823', idempotency_key: 'order_45521_attempt_1' }) });

Example response: json { "id": "pay_7Xk3mN9qR2wT", "status": "processing", "amount": 4999, "currency": "USD", "exchange_rate": null, "created_at": "2024-03-15T14:22:31Z" } [document continues through all sections]

Parameter	Type	Required	Description
amount	integer	Yes	Amount in smallest currency unit (e.g., cents)
currency	string	Yes	ISO 4217 currency code (e.g., "USD", "EUR") — new in v2
customer_id	string	Yes	Customer identifier
idempotency_key	string	Recommended	Unique key to prevent duplicate charges

Executive Summary (reproduced in full):

Meridian Payments API v2.0 — Summary of Changes

What Changed and Why

Meridian Payments API v2.0 expands our payment processing capabilities in two meaningful ways. First, we now support 28 currencies, enabling your customers to pay in their local currency without additional integration work on your end. Second, we replaced the previous status-checking model with a real-time notification system: instead of your system periodically asking "has this payment completed?" the API now proactively notifies you the moment a payment status changes. This is faster, reduces unnecessary server load, and provides more reliable delivery confirmation.

What This Means for Your Current Integration

Your existing integration will continue to work through December 31, 2024. After that date, one component of the previous version — the status-polling endpoint — will be retired. We are also introducing a required currency field in payment requests, which you were not previously required to specify.

These two changes require a brief integration update on your end. We recommend a two-week parallel testing period before you fully transition to v2.0, and our engineering team is available to support that process. We have documented the exact changes required in our technical migration guide.

Recommended Actions and Timeline

Now: Review this summary with your technical lead and confirm the migration plan

By [date + 14 days]: Complete integration updates and begin parallel testing

By [date + 30 days]: Switch fully to v2.0 and confirm successful transition

By December 31: Required — v1 status-polling endpoint retired

Questions? Your Meridian account manager can connect you with our integration support team directly.

Full Analysis: What Made the Difference

Context provision: Raj gave the AI the actual API specification — real endpoints, real parameters, real error codes. This is the single most important change. Without real technical context, AI cannot generate real technical documentation.

Dual-audience structure: Rather than running two separate prompts, Raj structured a single prompt with two clearly delineated document sections. This approach ensures both documents are generated from the same source context — preventing inconsistencies between them.

Format precision per audience: The technical document format specification listed exactly what sections to include, what elements each section needed, and what formatting to use (tables for parameters, code blocks for examples). The executive summary format was structured around the three questions the audience actually cares about — a brilliant reframing that the AI honored exactly.

Constraint clarity: "No code. No HTTP terminology. No acronyms without definition" for the executive summary are enforceable constraints. The AI followed all three. Compare this to Raj's first attempt, where no constraints produced an executive summary full of terms the intended audience would not understand.

Tone specification per audience: Technical documentation gets "No prose padding — this is a reference document." The executive summary gets "Confident, clear, reassuring without minimizing real migration requirements." Two different tones, specified explicitly, for two different readers.

Lessons for Technical Communicators

For documentation tasks, source material is non-negotiable. AI cannot generate accurate technical documentation from a vague description. It will generate plausible-sounding but inaccurate specifics. Provide the actual specifications, and you get real documentation.

Dual-audience prompts are powerful. When two documents share source context, building them into a single structured prompt ensures consistency and saves a full prompt-plus-editing cycle.

Technical audiences and executive audiences need different success criteria. Raj's breakthrough insight: instead of asking "what should this executive summary say," he asked "what three questions does this audience actually need answered?" Prompting around the reader's question, not the writer's structure, produces dramatically more useful output.

The 20-minute investment test. Raj's high-performance prompt took 20 minutes to build. It produced two documents that were essentially production-ready. His previous approach (two quick prompts) took 5 minutes to write and 3+ hours to edit. The time math strongly favors investment upfront.