A strategic guide to AI for Technical Authors

Writing for LLMs

In the past, Technical Authors wrote exclusively for human readers. Today, your content has a second, equally important audience: Large Language Models (LLMs). These systems “read” your documentation to provide answers to users.

If you write content that follows good technical writing principles, you will, in the main, meet the needs for both humans and AI systems. However, there are some adaptations you can make to optimise it for AI.

In short, writing with LLMs in mind means being more intentional about structure, clarity, and context, rather than abandoning good documentation practices.

Why LLM-friendly documentation matters

Users are increasingly accessing documentation through AI-powered tools. Chatbots, code assistants, and search interfaces use LLMs to understand queries and retrieve relevant information.
People often find what they need from the AI summaries at the top of the Google search results.
For example, developers might ask questions like “How do I authenticate with the API” to an AI assistant rather than manually searching through documentation.

If your documentation isn’t structured in a way that LLMs can parse and understand, it becomes invisible to this growing segment of users.

The LLM needs to identify the relevant sections, understand the context, and synthesise an accurate response. And well-structured documentation makes this process reliable and accurate.

Key principles for LLM-optimised documentation

Writing for LLMs might require some changes to how you structure and present information. We’ve described some of these below.

Use clear, descriptive headings

Headings serve as signposts for both human readers and LLMs. Make them descriptive and specific.
For example: Instead of “Advanced features”, use “Configuring custom authentication providers”.

Provide complete context in each section

LLMs often retrieve individual chunks of content rather than entire documents or long topics.
This means each section should be relatively self-contained. If you mention a concept, briefly define it or link to its definition. Don’t assume the reader has read previous sections. Every page is Page One.

Use consistent terminology

Pick one term for each concept and stick with it. If you alternate between “user account”, “account”, and “user profile”, a LLM might struggle to understand these refer to the same thing.
Of course, consistency helps machines and humans.

Structure information hierarchically

Use proper heading levels (H1, H2, H3) to show the relationships between concepts.
Having a hierarchy helps LLMs understand separate the primary information from the supporting detail. A flat structure with no hierarchy is difficult for LLMs to parse.

Include code examples with context

When including code snippets, explain what they do and when to use them. Don’t assume the surrounding text provides sufficient context.

For example: A code block with a comment such as “//Authenticates user with OAuth 2.0” is more useful to an LLM than a standalone block.

Write in clear, direct language

Avoid ambiguity, idioms, and cultural references that might confuse LLMs.

Metadata and structure

LLMs benefit from structured metadata. If you can:

• Use semantic HTML or markdown (headings, lists, tables) rather than relying on visual formatting (bold, larger fonts)
•  Include schema.org markup, particularly for API documentation
• Add alt text to images and diagrams
• Use consistent file naming conventions
• Consider including a machine-readable API specification (such as a Swagger file) alongside human-readable documentation

Testing your documentation with LLMs

Before publishing, you should test how well the LLMs can extract information from your documentation.

For example:

• Ask an LLM to summarise key sections
• Enter typical user questions and see if the LLM can find the correct information
• Check if the LLM can accurately extract code examples and explain them
• Verify the LLM correctly interprets technical terms and doesn’t confuse similar concepts

Using AI to be more efficient

AI tools can handle some of the time-consuming aspects of technical writing. This can allow you to focus on higher-value activities.

First drafts and content generation

AI can generate first drafts that:

• Provide the AI with source materials (API specs, product requirements, meeting notes) and ask it to draft documentation
• Use AI to expand bullet points into full paragraphs
• Generate multiple variations of explanations to find the clearest approach
• Create initial outlines and structure for complex documents

The AI-generated draft won’t be ready for publication. It can speed up the writing process by giving you something to refine rather than having to create from scratch.

Editing and refinement

AI is good at editorial tasks:

• Identifying inconsistencies in terminology, tone, or formatting
• Suggesting improvements to clarity and readability
• Spotting grammatical errors and typos
• Simplifying complex sentences while preserving technical accuracy
• Highlighting potential ambiguities or areas that need clarification

It can reduce the time you spend on manual editing.

Research and information gathering

Before writing, Technical Authors often need to gather information from various sources. AI can help by:

• Summarising long technical documents or meeting transcripts
• Extracting key information from multiple sources
• Comparing different versions of documentation to identify changes
• Analysing code repositories to understand functionality
• Identifying gaps in existing documentation

Template and boilerplate generation

A lot of technical documentation follows predictable patterns. You can create templates and use AI to generate similar documentation for new features or products. It maintains consistency, which means less editing work for you to do.

Documentation maintenance and updates

Keeping documentation current is one of the most time-consuming aspects of technical writing.

AI can assist with:

• Identifying outdated information by comparing documentation to current product behaviour
• Suggesting updates based on product changes
• Propagating changes across multiple documentation pages
• Checking for broken links and outdated screenshots
• Updating code examples to use current syntax and best practices

Workflow automation

AI can also automate workflows.

For example:

• Generating documentation from code comments and API specifications
• Creating documentation update pull requests when code changes in a repository
• Analysing user feedback and support tickets to identify any gaps in the documentation
• Updating documentation versions when products are released

Looking ahead

AI technology continues to evolve rapidly. Technical Authors who embrace AI now will be well-positioned for emerging capabilities such as real-time documentation updates, advanced personalisation, and seamless integration between documentation and products.

To get the most from an AI system, it needs content that follows technical writing and information design best practices. As Technical Authors already have those skills, it seems likely there’ll still be a need for them.

The role is evolving. Technical Authors will probably spend less time on mundane tasks; that will be done by AI systems. Technical Authors can focus on understanding users, designing effective information architecture, ensuring accuracy, and maintaining the human touch that makes documentation truly valuable.

AI is a tool that amplifies your expertise. Used thoughtfully, it enables you to produce better documentation, reach more users, and focus on the creative and strategic aspects of technical writing that require human judgement and insight.