This guide covers how to write and structure knowledge base articles so they're discoverable across three related but distinct channels: traditional search engines, answer engines, and generative AI systems. Following these practices ensures your articles are discoverable, improve click-through rates, and deliver a better experience however a reader — or a system answering on their behalf — arrives at your content.
As established in the What Makes Documentation Good guide, these three disciplines reinforce each other more than they compete:
- SEO (Search Engine Optimization) helps a traditional search engine index and rank your article for the terms people search.
- AEO (Answer Engine Optimization) helps your content be extracted directly as a concise answer — in featured snippets, voice assistant responses, and "quick answer" boxes.
- GEO (Generative Engine Optimization) helps a generative AI system retrieve, understand, and cite your content accurately when synthesizing an answer to a user's question.
An article with a descriptive title, a direct answer up front, clear headings, and one clearly stated fact per section tends to perform well across all three. This guide covers how to actually write to that standard.
Meta Title Guidelines
- Keep titles concise and descriptive, ideally between 50–60 characters. This is a tighter constraint than the general on-page H1 guideline in the Headings and Titles guide (~70 characters) — the meta title is what appears in a search result and is truncated more aggressively than the on-page heading. See the Article Titles section of that guide for how to keep the two aligned in meaning even when their lengths differ.
- Include primary keywords at the beginning of the title.
- Ensure titles accurately reflect the content.
- Avoid redundancy and keyword stuffing.
- Optionally add your brand name at the end, if space allows.
Example: Configure SSO using Okta
SEO Description Guidelines
- Write descriptions between 155–160 characters.
- Make them concise and informative.
- Use primary and secondary keywords naturally.
- Align with user intent — answer what the reader is actually searching for.
- Add a call to action where it fits naturally: "Learn how...," "Get started with...."
- Ensure each article has a unique description; duplicate descriptions across articles undermine both SEO and AEO, since neither system can tell the articles apart from their summaries alone.
- Avoid keyword stuffing.
Example: Learn how to configure single sign-on using Okta for secure, seamless access with organizational credentials.
Optimizing Article Structure
- Use clear, descriptive headings (H2, H3, H4) that include the terms readers actually search for — see the Place findable terms in headings, not just titles section of the Headings and Titles guide for the full reasoning.
- Add internal links to related knowledge base articles — typically one to three, placed where they're genuinely useful to the reader's next step. See the Cross-linking Structure section of the Structuring a Knowledge Base guide for the full rule on when and how to cross-link.
- Include external links to authoritative sources where relevant, sparingly.
- Keep the URL slug concise, lowercase, and keyword-friendly, avoiding stop words ("and," "the," "of"). See the Structure and Discoverability section of Structuring a Knowledge Base for the full rule on stable, descriptive URLs and redirects.
Example slug: /configuring-sso-okta-saml
Writing for AEO: The Extractable Answer
An answer engine (a featured snippet, a voice assistant, a "quick answer" panel) looks for a short, self-contained, directly stated answer — usually the first sentence or two of a section — that it can lift out and present without needing the rest of the article for context.
- State the direct answer to the article's core question as early as possible, ideally in the first sentence after the heading it answers, before elaborating with detail, caveats, or examples.
- Make that first sentence stand on its own: avoid pronouns or references that depend on a previous sentence ("This makes it easier..." — easier than what?).
- Match the phrasing of your heading to how someone would actually phrase the question, since answer engines frequently match a heading to a spoken or typed query almost directly.
- Where a question is genuinely common enough to be searched as a question, a question-format heading is appropriate — see the exception noted in the Headings and Titles guide.
Writing for GEO: What AI Systems Retrieve and Cite
A generative AI system retrieves passages from your content and synthesizes them into an answer, often citing or paraphrasing your article as a source. Content that's easy for an AI system to retrieve and cite correctly shares almost all the same qualities that make it good for a human reader:
- Clear, direct, unhedged statements — see the Plain Language Principles and Common Voice and Tone Mistakes guides. A hedged or vague sentence gives an AI system nothing solid to extract.
- Consistent structure and terminology across articles, so a retrieval system can correctly relate one article's claim to another rather than merging or confusing similar-sounding content — see the Structuring a Knowledge Base guide's discussion of GEO.
- One clearly stated fact per section, rather than several ideas packed into one paragraph, so a retrieval system can isolate the specific section that answers a given question.
- Accurate, current content — see the Documentation Lifecycle guide on why an unmaintained article can mislead an AI system long after human readers stop finding it through normal navigation.
Readability
Search engines, answer engines, and AI systems all favor content that's easy to parse — readability isn't only a courtesy to human readers.
- Aim for a general readability level appropriate to your audience; see the concrete self-check (Flesch-Kincaid grade level around 8–10 for most product documentation) in the Plain Language Principles guide.
- Keep sentences under 20–25 words in most cases.
- Limit paragraphs to roughly 150 words, or three to five sentences.
- Break content into sections with clear headings rather than dense, unbroken blocks of text.
- Avoid long, complex sentences that bury the main point in subordinate clauses.
Common Mistakes to Avoid
- Missing SEO titles or descriptions.
- Using duplicate meta descriptions across articles.
- Keyword stuffing in titles or descriptions.
- Long, complex sentences that reduce readability and extractability alike.
- Forgetting to add internal links.
- Burying the direct answer to a question deep in the article instead of stating it early, where both human readers and answer engines can find it quickly.
Self-Audit Checklist
Before publishing, check the article against these questions:
- Is the meta title between 50–60 characters, with the primary keyword near the start?
- Is the meta description 155–160 characters, unique to this article, and free of keyword stuffing?
- Do headings use the terms readers actually search for?
- Are internal and external links present where genuinely useful, not just for their own sake?
- Is the URL slug concise, lowercase, keyword-friendly, and free of stop words?
- Does the article state a direct, self-contained answer early, before elaborating?
- Is the content free of hedging and vague claims that an AI system couldn't confidently extract or cite?
- Is terminology consistent with how the same concept is described elsewhere in the knowledge base?
- Does the article meet your readability targets (sentence length, paragraph length, heading frequency)?
- Is the content current and accurate, so it's safe for a search engine or AI system to keep citing it?