Problem

AI models are predictive engines, not reasoning engines. If an API usage example is incomplete, uses ambiguous placeholders, or relies on implicit knowledge, the AI will “hallucinate”. It invents missing pieces based on general training patterns. These inventions are frequently incorrect, leading to developer frustration.

Why it matters

Hallucinated code destroys user trust. When a developer asks an AI for help and receives broken code, they blame the software for being “buggy” or “poorly documented”. Minimising hallucinations is critical for maintaining your project’s professional reputation.

Approach

Practice Defensive Documentation. Write extremely explicit, fully instantiated code blocks that leave no room for ambiguity. Never assume the reader (or the AI) knows the necessary imports, environment variables, or prerequisite configurations.

Implementation

1. Fully-Qualified Code Blocks

Always include the necessary imports or setup code in every snippet. This ensures that when an AI chunks your documentation, the code block remains a self-contained unit of truth.

• ❌ Hallucination Risk:

  const config = loadConfig(); 
  

• ✅ Hallucination Proof:

  import { loadConfig } from "@docmd/core";
  const config = loadConfig();
  

2. Concrete Examples Over Placeholders

Avoid using vague placeholders like your-api-key or env-name. Provide concrete, valid examples or use comments to specify strict enum requirements.

// Valid environments: "development", "staging", "production"
const app = init({ env: "production" });

3. Inline Code Comments

Place critical requirements inside the code block as comments, rather than only in surrounding paragraphs. AI models weigh comments within code highly when generating similar snippets.

  // REQUIRED: Must be an absolute path
  outputPath: "/var/www/html/docs"

4. Categorised Warnings

Use Callouts to clearly mark deprecated features or breaking changes. AI models are more likely to respect a ::: callout warning block than a simple sentence in a paragraph.

Trade-offs

Defensive documentation makes code blocks longer and more repetitive. Human readers may find seeing the same import statements tedious. However, the benefit of having “AI-proof” documentation that reduces support tickets far outweighs the minor cost of verbosity.