5 Writing for the Web #
Technical documentation on the Web serves two critical audiences: human users seeking immediate solutions and AI search systems that retrieve and synthesize content. Create engaging, clear and highly structured content. This helps your audience find answers quickly and ensures discoverability by modern search engines and AI assistants.
5.1 Structuring topics #
The most important thing to do with your Web copy is to help users get answers to their questions as soon as possible. To achieve this, use the modular approach of topic-based authoring. Create and maintain documentation in discrete chunks, called topics.
Topics have the sole purpose of supporting users in their tasks. Each topic focuses on one specific subject and has one distinct purpose. Write topics so they stand alone and function in context with other topics. Ensure they are reusable across different contexts.
Apply the following recommendations to structure your Web content:
Put your most important information first. Users typically decide whether they will stay on your page within 3–5 seconds. Make sure your copy helps users understand the big picture right away.
Write for scanners. Help readers find the answer to their question immediately. Create headlines that are clear and to the point. Break long headlines into a main heading and sub-heading. Ask yourself: Is it easy to see the benefit of the page at a quick glance?
Defeat walls of text. Neither human readers under pressure nor AI systems want to read a ten-paragraph essay to find a single command or configuration setting. Layer and break up your content into small, logical sections.
Apply the TL;DR first rule. Lead each section with a direct answer or summary. If you bury the key information at the bottom of the page, readers and AI systems may skip it.
Include a table of contents. For longer documents, a table of contents with anchor links helps human users jump to the exact answer they need, while assisting AI systems in building an accurate content map of your documentation.
5.2 Optimizing for SEO, GEO and AEO #
The Web search landscape is rapidly evolving as traditional search engines integrate artificial intelligence (AI) to generate direct answers. Modern users rely on both organic search and conversational AI assistants to find solutions. To maximize discoverability, documentation must adapt to three strategies: Search Engine Optimization (SEO), Generative Engine Optimization (GEO) and Answer Engine Optimization (AEO).
Search Engine Optimization (SEO) is the practice of optimizing content to rank high in traditional organic search engine results. SEO targets Web crawlers and indexers to index pages for keyword-based search queries. It relies on page headers, metadata, indexability and high-quality link structures.
Answer Engine Optimization (AEO) is the practice of optimizing content to provide direct, concise answers to user queries. AEO targets platforms like search snippets, AI overviews and voice search. It relies on content types such as short definitions, 50–100 word summaries and FAQs.
Generative Engine Optimization (GEO) is the practice of optimizing content to be cited as a trusted, authoritative source by large language models (LLMs). GEO targets conversational AI platforms like Gemini or ChatGPT. It relies on in-depth guides, case studies and extensive technical research.
Traditional SEO remains the foundation for AI search discoverability. Because AI models retrieve their grounding data from high-ranking Web pages, achieving a high organic search ranking remains the primary gateway for AI visibility.
5.3 Writing GEO- and AI-friendly content #
To win in AI search, you must make your documentation highly visible and structured so that LLMs can extract, process and cite it easily. Content optimization requires shifting your focus from keyword matching to satisfying both semantic human intent and AI grounding behaviors.
Apply the following comparative practices to optimize documentation for both traditional search engines and AI engines:
| Feature | Traditional SEO | GEO and AEO |
|---|---|---|
| Headings | Generic headings (such as “Setup” or “Usage”) | Real queries and actions (such as question-based: “How to configure a Samba server?”) |
| Structure | Narrative or linear stories | Modular content blocks (one to three paragraphs) addressing a single intent; use of lists, procedures, tables and Q&A; short sentences of 15–20 words |
| Abstract and first sentence | Weak or generic introductions or broken structures explaining background information | Answer nuggets (lead with a direct, objective 40–80 word answer in the first one or two sentences) |
| Metadata | Keyword-stuffed descriptions | Direct “What is” definitions and task-oriented phrasing (such as “Learn to...”) |
| Images | Simple references (such as “See screenshot”) | Text-based code snippets and detailed alt text to explain the context |
5.3.1 Mastering content representation for AI models #
LLMs decide which sources to cite based on the structure and clarity of the content. Apply these three principles to master representation in AI search:
Ensure extractability. Break complex technical procedures into small, atomic chunks that stand alone. Each section should contain all the necessary context to be useful on its own.
Establish semantic authority. Address user intent and the true meaning behind search queries, rather than repeating exact keywords. Provide thorough, factual solutions.
Maintain strict consistency. Align terminology and facts across all your documentation. Discrepancies or contradictory claims across files cause AI models to hallucinate or reject your content.
Avoid weak patterns. Do not write ambiguous text, contextual dependencies (such as referring heavily to other unlinked sections) or low-density introductions.
5.3.2 Brainstorming and researching keywords #
Search engines and AI crawlers must recognize your core topics. Search the phrases you want to rank for to learn what type of content search engines deem best for a specific keyword. Always prioritize approved SUSE documentation terminology.
Do not stuff your content with keywords. The keyword ratio for an article should be 2–4%. This ratio represents approximately eight to ten keywords per 500 words.
5.3.3 Structuring headings in a hierarchy #
Organizing your headings in a clear hierarchy makes a larger content piece easily scannable. A structured hierarchy helps human readers scan the page and assists search engines in understanding the context of your content. Use standard markdown heading tags (such as H1, H2 and H3) sequentially without skipping levels.
5.3.4 Creating concise and effective titles #
For search engines to recognize meta titles, you must deliberately create them in the designated section of each document. If a title is not provided, search engines may extract them from the H1 or H2 heading.
Follow these guidelines when creating titles:
Keep the title under 55 characters if possible, and never shorter than 29 characters.
Integrate keywords naturally, including product names where relevant.
Place the primary keyword in the page title, first H1 heading, first paragraph and URL slug.
Use secondary keywords in H2–H3 headings, alternative (alt) text for images and the meta description to support discoverability.
For lengthy product names, define each abbreviation at first use by placing the full term in parentheses after it.
5.3.5 Creating concise and effective meta descriptions #
Meta descriptions must be specifically authored in the appropriate section of each document. If a meta description is missing, search engines may extract it from the abstract.
Follow these rules when writing meta descriptions:
Keep the description between 120–155 characters.
Ensure it is a single, complete sentence that accurately summarizes the content.
Use the following ready-made AI prompt template to generate compliant meta descriptions during your editing workflow:
You are an expert technical writer specializing in SEO and GEO.
Write a single, compelling meta description for the following documentation page content.
Follow these rules strictly:
1. The description MUST be a single, complete sentence.
2. The description's length MUST be between 120 and 155 characters.
3. It MUST be an accurate and concise summary of the provided text.
4. Write in a neutral, professional and helpful tone.
5. Your output MUST ONLY be the description text itself.
Do NOT include quotation marks, labels like “Description:” or any other explanatory text.5.3.6 Linking to and from your content #
Links are critical to establishing the authority and relevance of your content. Plan your links according to these two types:
Internal links lead to and from other pages within the same domain. They help establish the relationship between two pieces of content. Internal linking helps search engines discover and index new pages on the Web site. It also allows AI tools to map the structure of your content.
Inbound links lead to your content piece from a different domain (such as from
sap.comtosuse.com).
External links to high-quality, credible Web sites increase the validity of your own Web site. High-quality links help pages rank higher in organic search results. Always link to trusted, authoritative sources like upstream projects or developer sites. Avoid linking to direct competitors or obvious clickbait sites.
5.4 Ensuring accessibility #
Accessible technical documentation ensures that information is available to all users, regardless of their physical or cognitive abilities. Many users rely on assistive technologies, such as screen readers and alternative input devices, to navigate Web pages. Ensuring accessibility supports compliance with legal requirements and makes documentation more usable for everyone.
Apply the following guidelines to make your content accessible:
Provide alt text for images. Screen reader users need descriptive alt text to understand the purpose of an image. Describe the essential content and function of the graphic. For example, instead of writing “screenshot of settings,” write “The Settings menu showing the notifications option turned on.” Learn more about alt text markup in Section 7.10, “Figures”.
Write in plain language. Keep your sentences concise and avoid unnecessary jargon. Plain language helps non-native speakers, users with cognitive disabilities and AI systems that parse your content.
Structure tables correctly. Assistive technologies must be able to interpret table layouts. Always use table headers for columns and rows to provide context. Avoid leaving cells empty; if no data applies to a cell, explicitly write “N/A” or “Not applicable.” More about tables in Section 7.22, “Tables”.
5.5 Writing for a global audience #
Every documentation file is a candidate for localization (translation). To ensure your content translates well, you must make sure that the original English text is clear, correct and simple. Direct prose and simple sentence structures improve translation memory reuse and reduce translation costs.
Apply the following guidelines when writing for a global audience:
Keep sentences short. Shorter sentences help both translators and your target audience to understand the content. Aim for sentences with 25 words or less.
Be consistent. Use the same terminology and sentence structures for similar content. Use identical phrasing for repetitive tasks. This practice increases translation memory reuse and ensures consistent user experiences.
Make clear statements. Do not use imprecise words like "should" or "could" when giving instructions. Be direct and explain what happens or what the user must do.
Mark non-translatable text. Use tags as defined in Chapter 8, DocBook tags or use the ITS tag feature to mark all content that should not be translated (for more information, see Section 8.2, “Using ITS tags”). Use entities for product names, example names, etc. Always mark code as such so that it is not translated.
Use international examples. Do not use country-specific words, cultural references or local examples. Use common international examples instead (such as standard host names or IP addresses).
Minimize graphics. Keep images and screenshots to a minimum. Each graphic must be updated whenever the software user interface changes, which increases maintenance efforts.
Do not break sentences. Do not use hard breaks within sentences to avoid breaking translation strings.
Do not break sentences with list items. Do not split a single sentence across a list structure. This practice makes translation impossible because different languages use different word order structures.
Incorrect (sentence split by a list):
You can use the following commands: -a -z -b to start the system update.
Correct (complete sentence followed by a list):
To start the system update, you can use the following commands: -a -z -b
Use proofreading and review options. Have your content reviewed by peers or linguistic editors to detect misunderstandings and style inconsistencies before publishing.