Writing for robots means writing content that is easily understood by search engines and AI systems. Following best practices for writing for robots can improve the quality of answers that AI systems provide.
Content findability now spans both traditional search engines and robots. Search Engine Optimization (SEO) and writing for Large Language Models (LLMs) both improve page findability. To learn more, see Findability (SEO and LLM) Guidelines.
Be Explicit
Robots rely on clear and explicit language to understand the context and meaning of the content. Robots can interpret only what is on the page and can't parse implicit content or hints like human readers can. For example, if you use the word "this", you should clearly define the word using something like "this example" and not leave the word ambiguous.
Use clear and explicit language to convey the context and meaning of the content.
Use clear and descriptive headings that accurately reflect the content of the section.
Be explicit about the context in which you describe an expression.
Be Specific
Robots need specific information to understand the content. Vague or general statements can lead to misinterpretation or confusion.
Use unique, descriptive titles for pages and sections.
Use specific keywords and phrases that accurately reflect the content of the page.
Maintain content regularly to remove any outdated or irrelevant information.
The following example shows a specific and descriptive title on the left, and a vague and general title on the right:
Use | Avoid |
|---|---|
Reference Architecture for Scalable Web Applications | Web Apps |
For more information about effective titles see Titles in the SEO Guidelines section.
Keep It Simple
While providing enough information is important, it's equally important to keep the content simple and easy to understand. Over-describing exceptions and including related topics can confuse AI systems.
Ensure that the most important topic on the page is clear and easy to find.
Reduce noise by avoiding tangentially related information.
Link out to related, non-essential information instead of describing it on the same page.
Use URL slugs that are descriptive of the content on the page.
Be Concise and Elevate Important Details
AI systems prioritize the beginning of the content when determining its relevance to a query. If the most important information is buried deep within the content, it may be overlooked.
Place the most important information at the beginning of the content.
Use appropriate headings and subheadings to break up the content and make it easier to scan.
Use bullet points and lists to highlight key information.
Avoid expanding on less important or relevant topics within the document.
Use Structured Data
Structured HTML (also called semantic HTML and structured data) communicates to robots what our content is, and what it is about. Our tools translate metadata in the rST file into structured HTML that robots can interpret in a few ways.
Most importantly, use the .. procedure:: directive instead of a
numbered list, because the procedure directive maps to "How To"
metadata that signals to robots that a step-wise procedure follows.
This same process allows Google to take a recipe and present it in a search result as steps. Metadata behind the scenes tells Google how to parse that particular type of content.
Other elements include our taxonomy values, like genre, product, and programming language. Code examples also use structured HTML to indicate the programming language and that the content is a code example.
Use Example Values Effectively
When writing code examples or guides that use a specific MongoDB command, use the exact command name before you use example placeholder values in a code example. This helps AI systems understand the actual name of the command in addition to usage examples.
Use | Avoid |
|---|---|
The find() method retrieves documents from a collection.Use db.collection.find() to query documents. The following example usesthe find() method to query the inventory collection:db.inventory.find({ status: "active" }) | Use the find() method to query documents as shown in the following example:db.inventory.find({ status: "active" }) |
Answer User Questions Using Their Words
When writing content, use the terms that users use when they search for information related to your topic. Use these terms naturally throughout the content to improve its relevance for AI systems that are answering user questions that use those terms.
Use search and chatbot data to understand the terms and phrases that users commonly use when searching for information related to your topic.
Use these terms naturally throughout the content, including in headings, subheadings, and body text.
Avoid keyword stuffing, which can negatively impact the readability and relevance of the content.
Add Appropriate Synonyms
Using synonyms can help improve the relevance of the content for AI systems. Different users may use different terms to describe the same concept, so incorporating synonyms can help ensure that the content is relevant to a wider range of queries.
The following example shows how to include a synonym, in this case "unique", to
describe the db.collection.distinct() command:
Use | Avoid |
|---|---|
Definition db.collection.distinct(field, query, options)Finds the distinct values for a specified field across a single collection or view and returns the unique results in an array. | Definition db.collection.distinct(field, query, options)Finds the distinct values for a specified field across a single collection or view and returns the results in an array. |