Instruction file imported from SUSE/doc-suse-ai (.github/instructions/08-web-writing.instructions.md). Copyright stays with the author.

Writing for the Web, SEO and GEO

Optimize content for AI-driven search, scanning and fast comprehension:

Structure: 

• Break text into small, modular "atomic" chunks (1-3 paragraphs) that can stand alone without losing context.
• Use the "Inverted Pyramid" rule: lead with a direct, 40-80 word answer to the primary user intent at the very top.
• Create headings (H2/H3) in the form of natural-language questions that mirror user prompts Meta Descriptions: Write a single, complete sentence between 120 and 155 characters. E-E-A-T: Include specific data points, unique case studies and primary source citations.

Prefer:

• one topic per section
• short introductions
• task-oriented explanations
• explicit wording
• predictable structure
• information ordered by user importance

Ensure:

• users can understand the purpose of the page within seconds
• sections remain understandable outside their original context
• content supports both human readers and search indexing
• content is accessible to global audiences

Avoid:

• long narrative introductions
• unnecessary background information
• large unbroken text blocks
• hidden conclusions
• ambiguous references
• idioms and culturally specific phrasing
• mixing multiple unrelated goals in one topic

Example

Avoid: a long narrative intro Use: starting your article with: "H1: Dealing with Boot Problems. A boot problem occurs when the system fails to load the OS. To fix this, restart the SAN and check active file locks."