Best practices for GenAI - Articles

Last updated
Save as PDF

General best practices for article creation for Gen AI, including guidance for titles, headings, content format, and content structure.

Titles

An article title should describe the topic clearly and specifically using the words your readers actually use.

Be specific. "Reset a customer password" tells you what the article does. "Password information" does not.
Use the reader's language. If customers typically ask "How do I cancel my subscription?", the title should include the words "cancel" and "subscription." A title like "terminate service" will be harder to find and understand.
Focus on the outcome, not the feature or the internal system name.

Examples

Version numbers, status labels, and internal identifiers make a title harder to scan and add little value for readers.


Before	After
Password Info	Reset a Customer Password
Billing	Update the Credit Card on Your Account
SSO Documentation	Set up Single Sign-On for your team
Article #4123	Troubleshoot a failed order
MFA Configuration Guide V2 Final	Enable Multi-Factor Authentication

Headings

Headings break an article into sections, and give people and AI models clean pieces of content to work with. When retrieval finds a relevant section, the heading is part of what tells the AI what that section is about.

Headings should be:

Descriptive: Explain what is in that section without reading further.
Consistent: If one heading is a question, do not make the next a noun phrase.
Contextual: Relate to the section content, rather than serve as a generic placeholder.

Examples

Before

These headings give no context:

Overview
Details
Additional Information
Notes

After

Use headings that describe the actual content:

When to use multi-factor authentication
How to enable MFA for a single user
How to enable MFA for your whole team
Recovery options if a user loses their device

The "after" version reads like a useful table of contents, and each heading on its own is a signal about what that section contains.

Article content

Article content should focus on a single outcome. For example, if the goal is to explain how to reset a password, the article should only include that information. If there is other information that is related but not part of the password reset outcome, it should be in a separate article.
Language should be as simple as possible in order to reach the most varied audience. Natural, friendly language is similar to the way customers phrase their questions.
Use descriptive words to provide as much context as possible. Context is key for generative search, so include relevant context associated with the outcome desired to explain why the article is useful.
Context is better than keywords, because of how genAI groups related bits of information close to each other.
- Example: A user looking at bakery selections asks "What kinds of icing can I order?" The site content only refers to icing as "frosting" so no search results come up. In the past, content authors might have added the keyword "icing" to the end of the article (or somewhere else) without any context, in order to ensure that the page pops up in search results. Instead, to give the word contextual meaning for an LLM to identify its relevance to a query, authors should provide context. The updated content might look something like, "We offer several types of frosting and icing for our cakes, including..."
Content should be created in short, human-readable paragraphs. This allows for easier handling of information for both humans and GenResponses. When you have short paragraphs, GenResponses can more easily retrieve the relevant information from a page. When the answer for a GenResponse query comes from more than one page, this enables the correct context to be retrieved most efficiently from all pages.
Avoid acronyms or provide the description of the acronym within the article itself. Acronyms can be difficult for a GenAI model to manage properly. Early testing has shown that defining the acronyms both in a glossary of terms and in-line with the page content provides the best results.
- Example:
  Glossary of Terms: WFH - Work from Home - This would be a page which all user types have permissions to read.
  Inline: The WFH (Work from Home) policies reflect input from the employee survey.

Content format

Content structure

Organize the body of the article using a logical structure, with clear headings and subheadings based on the topic. Use bullet points and numbered lists to support findability.

Every article is in competition to be the most relevant article for the question asked. If the topic for the question exists in multiple articles, the article you deem as being the most relevant needs to surpass the relevancy of every other article in that topic for that question.

Tables

Create clear and easily digestible tables. Be sure to use clear definitions for headers and rows, and do not create tables within tables.
Add a summary of the table content, so it is clear what information is being presented, or what conclusions can be drawn. This context can improve generative AI tool performance.
Use the table and content length CSV to understand your site's table structures, and identify tables that may not be optimal for AI processing.

If you notice difficulty with table information, check the following:

Are table headers under 50 characters, and 4 words or less?
Does every cell have a value of more than 2 characters?
Do cells contain less than 100 characters and less than 50 words?
Are tables nested, or are there nested structures like <ul> or <ol> in the table?
Does the table have a description of the contents and explanations of the data before the beginning of the <table>? It is essential to provide context for GenAI.

For persistent issues with an article containing a long table, consider removing the page from the LLM index.

Example of a table that GenAI can use effectively:

Feature	Base Bronco	Big Bend Bronco
Cost	2-Door: $28,500 4-Door: $33,200	2-Door: $33,385 4-Door: $35,880
Engine	2.3L EcoBoost Optional: 2.7L EcoBoost	2.3L EcoBoost Optional: 2.7L EcoBoost
Transmission	7-Speed Manual with Crawler Gear Optional: 10-Speed Automatic with Trail Control	7-Speed Manual with Crawler Gear Optional: 10-Speed Automatic with Trail Control
G.O.A.T. Modes	Normal, ECO, Sport, Slippery, and Sand	Normal, ECO, Sport, Slippery, Sand, and Mud/Ruts
Wheels and Tires	16-inch silver-painted steel wheels 30-inch P255/70R16 all-season tires	17-inch Carbonized Gray-painted aluminum wheels 32-inch P255/75R17 all-terrain tires
4WD System	4x4 with part-time selectable engagement Optional: Advanced 4x4 with automatic on-demand engagement	4x4 with part-time selectable engagement Optional: Advanced 4x4 with automatic on-demand engagement