A few months ago, my engineering lead Slacked me a file: a system prompt for our new AI-powered note generator. He wanted me to look at that text file. I opened the file; the prompt felt like it was a lazy mess, bloated, ambiguous, and full of filler.
If they had used that prompt in production, every one of those extra words would end up on the API bill.
So, I took that prompt and spent about a week refactoring it using the same style guide, information architecture, and defensive writing rules that I use for my company's developer documentation. That was when I realised something:
Prompt engineering is not engineering at all. It is technical writing
The Sloppy AI writing
In software documentation, sloppy AI writing is mostly ineffective because it wastes tokens. When developers build LLM-powered features using prompts, they often treat the model like a human colleague.
I have seen devs writing prompts the same way they would write a message to a coworker on Slack. But that makes less sense for an LLM. An LLM does not read a prompt the way a developer reads a Slack message. It relies on the instructions and patterns in the text, so unclear and unnecessary wording can make the output less clear.
For example:
"Could you please be so kind as to analyse the following text very carefully,"
In the above prompt, you have just spent 15 tokens saying very little. I call this a lazy prompt. A lazy prompt is like a half recipe or, say, an easy recipe which unfortunately does not result in tasty food.
Why lazy prompts can crash your backend database
One of the biggest headaches our engineering team faced was parser failures. We needed the LLM to output raw JSON so our backend could ingest the data. Instead, the model kept returning conversational preambles:
"Sure! Here is the structured JSON clinical note you requested based on the transcript:"
{
"symptoms": ["cough", "fever"]
}
Because the model wrapped the JSON in markdown code blocks (json ...),
our backend parser threw a 500 error and crashed. The engineers’ first reaction was to write regular expressions and retry loops to strip out the markdown blocks and conversational text. But that resulted in another problem.
If the parser failed, the system automatically retried the API call, doubling the cost and latency for that transaction. Our production audits showed that 34% of our API calls were retries triggered by formatting failures. As a technical writer, my approach was to write defensively. What do I mean when I say this? Let’s understand with an example.
As technical writers, we don’t just tell users how to install a plugin. We also explain what to do when the installation fails. This is a defensive technique of writing. I applied the same thinking to that prompt and added explicit negative scenarios and error-handling patterns.
I removed conversational padding:
For example:
“Do not include introductory or concluding remarks. Do not say ‘Sure, here is the JSON.’ Return only the raw JSON object.”
Banned markdown blocks: For example: “Do not wrap the output in markdown code blocks (such as ```
json). Start the response directly with the opening curly brace {.
Defined empty states like: “If no medications are discussed, return an empty array []. Do not omit the key, and do not return null."
By writing defensively, we dropped our parser failure rate to near zero. We did not write a single line of regex or retry logic but just wrote better instructions, and that is what a technical writer does all day.
How large language models read and why layout is everything
In Technical writing, structure matters a lot. Writing in a structured manner gives readers a better mental model. For example, good structured writing will have a high-level overview at the top, step-by-step guides in the middle, and reference tables at the bottom. LLMs require the same kind of structured information.
Research from “Landmark research from Stanford and UC Berkeley (Liu et al., Lost in the Middle)” showed that an LLM’s retrieval accuracy drops significantly when key instructions or data sit in the middle of long, unstructured contexts.
The model pays the most attention to the beginning and the end of the prompt; the middle part is skimmed and scanned. To counter this middle-part attention degradation, as a prompt writer, it is important to structure your prompts like software specifications:
Role / System Persona (Head): Establish the context and behavioural boundaries.
Goal / Objective: Define the exact task to be performed.
Constraints (Negative & Positive): Set the guardrails, including what to do and what not to do.
Context / Input Data: Put the raw content to be processed inside clear XML tags, such as
<transcript>...</transcript>.Output Schema (Tail): Put the precise response format at the end, where the model’s attention is closest.
The point is not to make the prompt look neat, but to put the important instructions where they are less likely to get lost.
The “lazy” prompt vs. the “tech-written” spec: Comparison
To see these principles in action, let us look at a real-world scenario from my documentation. Imagine we are building an AI feature that parses unstructured clinical transcripts into a structured JSON format for an electronic health record (EHR) system.
The lazy prompt example:
plaintext
You are a helpful medical assistant. I am going to give you a transcript of a doctor talking to a patient, and I want you to extract the patient's symptoms and any medications they discussed.
Please put them in a JSON format so my system can read it. Make sure you are accurate and don't make things up. If there are no medications, just leave it blank.
Here is the transcript:
[Transcript content]
The Flaws in the above prompt:
Ambiguous Schema: “JSON format” is highly non-deterministic. The model may return {"symptoms": [...], "medications": [...]} in one run, and {"patient_symptoms": ..., "drugs": ...} in the next.
No Negative Scenarios: The model will almost certainly include conversational fillers like “Sure, here is the structured JSON for the transcript you provided:”, which will crash any standard JSON parser.
No Error Handling: “Leave it blank” could mean returning an empty string, an empty array, null, or omitting the key entirely.
How I would write this as a tech writer:
markdown
# Role
You are a clinical data parser. Your sole task is to extract symptoms and medications from clinical transcripts.
# Constraints
Output must be a single, valid JSON object matching the schema below.
- Do not include any conversational text, markdown formatting blocks (such as
```json), preambles, or postscripts.
- Extract only symptoms and medications explicitly stated in the transcript. Do not infer or extrapolate.
# Output Schema
{
"symptoms": ["string"], // List of symptoms explicitly mentioned. If none, return an empty array [].
"medications": [
{
"name": "string", // Generic or brand name of the drug.
"dosage": "string" // Dosage specified (e.g., "50mg"). If not specified, return "N/A".
}
] // List of medications. If none, return an empty array [].
}
# Input
Transcript: [Transcript content]
Let’s evaluate this prompt now:
Clear example: The explicit JSON schema and negative scenario guarantee that the output is immediately understandable by the AI.
Better Structure: The model has zero formatting decisions to make, dropping latency and eliminating reasoning cost.
Defensive writing: Clear instructions for empty states ([], "N/A") prevent the model from guessing or omitting keys.
Takeaway
AI has led to a quiet panic in the technical writing community, and many of the top-level executives think, why do we even need tech writers at all. We need to understand that the core skill of a technical writer is not just writing words; it is analysing complex software APIs, SDKs, and cloud systems, identifying edge cases, and constructing structured, unambiguous instructions.
As we move forward in the AI world, the demand for structured context architecture is going to skyrocket. Companies cannot build reliable AI features on top of sloppy AI content and conversational prompts. They need someone who treats language like code, and technical writers are the ones who understand information architecture best.
Top comments (0)