Problem

Human readers rely on visual cues and inferred context. AI agents consume raw text streams. Without rigorous semantic structure, models struggle to map relationships between concepts. This leads to poor reasoning and inaccurate coding suggestions.

Why it matters

If your documentation is not optimised for LLMs, developers using tools like GitHub Copilot or Cursor face more hallucinations. This degrades the developer experience. Users often blame your product for errors generated by their AI assistants.

Approach

Transition from a “visual-first” to a “semantic-first” mindset. Use standard Markdown features - strict header hierarchies, explicit code block tags, and descriptive alt text - to provide a machine-readable roadmap. docmd processes this structure into optimised outputs via the LLMs Plugin.

Implementation

1. Strict Header Hierarchy

Avoid skipping header levels for visual effects. A consistent hierarchy allows LLMs to understand the scope and relationships of different sections.

• # Title: The primary subject of the page.
• ## Major Concept: An atomic, high-level topic.
• ### Detail: A specific sub-task or property.

• ❌ Poor: Using ### immediately after # for a smaller font size.
• ✅ Good: # Installation followed by ## Prerequisites and ### System Requirements.

2. Descriptive Metadata for Media

LLMs cannot “see” images or diagrams. Provide architectural context in the alternative text or an adjacent paragraph.

![System Architecture: The frontend React app communicates with the Node.js API via REST, which queries a Redis cache and a PostgreSQL database.](../../static/img/architecture.png)

3. Explicit Code Block Labelling

Specify the language for every fenced code block using Syntax Highlighting. This allows LLMs to parse the Abstract Syntax Tree (AST) correctly.

  "plugins": {
    "llms": {}
  }

4. Semantic Containers

Use Callouts rather than generic blockquotes to provide intent. docmd’s semantic containers help AI models distinguish core instructions from supplementary warnings.

Trade-offs

Semantic rigour requires discipline. You cannot use Markdown features purely as decorative elements. However, this discipline produces documentation that is significantly more accessible to both AI agents and human readers using assistive technologies.