Update robot use guidance

Author: cbullinger

.vscode/settings.json

@@ -1,6 +1,8 @@
 .. meta::
    :robots: noindex, nosnippet 
 
+.. _code-block-reference:
+
 =============
 Code Examples
 =============

source/reference/code-blocks.txt

@@ -18,22 +18,22 @@ Code Example Guidelines
    irrespective of language. Language-specific style guidelines and coding
    standards are in progress.
 
-Code examples demonstrate how to use our products programmatically. Our readers
-use these examples to learn, troubleshoot, or even copy and adapt them for
-their own needs. Well-crafted and well-maintained code examples improve the
-overall readability and quality of our Docs, helping build trust with users and
-reduce reported issues.
+Code examples demonstrate how to use our products programmatically.
+High-quality, well-maintained code improves our docs' usability, builds our
+credibility with users, and helps reduce reported issues.
 
 What is a Code Example?
 -----------------------
 
-We define a code example specifically as ***any block of code that is set apart
-from the surrounding copy in a page***.
+A code example is any size block of code set apart from regular text using a
+code-block directive. For details on valid directives, see the
+:ref:`code-block-reference` reference.
 
-.. TODO Add section BRIEFLY introducing semantic meaning and why it's relevant to code block vs. inline code
-
-Inline Code vs. Code Block
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+- Use code-block directives for all code examples. Code blocks are visually
+  distinct, easier to read, and better interpreted by robot users (such as
+  screen readers, AI models, and crawlers).
+- Do not use inline code markup to format code examples in ``monospace``. Use
+  inline code for short references within text (such as method names).
 
 1. Inline Code
 #. Code Block
@@ -66,18 +66,26 @@ Types of Code Examples
 
 .. NOTE related page: `Reference/Code Examples <https://www.mongodb.com/docs/meta/reference/code-blocks/`__
 
-We categorize code examples in our Docs as ***Usage Examples***,
-***Snippets***, or ***Sample Applications***. These categories and their
-subcategories have specific definitions and serve specific purposes.
+   Although "code example" and "snippet" are often used interchangeably, this guidance uses "snippet" to mean a context-less block of code.
+
+We categorize code examples into the following types:
 
-.. TODO adopt the Informational vs Actionable paradigm to explain the difference between usage examples and snippets
+- :ref:`Usage Examples <code-category-usage-example>`: Standalone code blocks
+  that show how to perform a task, including the relevant setup and context.
+- :ref:`Snippets <code-category-snippet>`: Code that illustrates a specific
+  concept or detail in the context a larger example, tutorial, or reference page.
+- :ref:`Sample Applications <code-category-sample-app>`: Runnable applications
+  demonstrating broader use cases.
+
+.. _code-category-usage-example:
 
 Usage Examples
 ~~~~~~~~~~~~~~
 
-Usage examples are self-contained code examples that establish parameters,
-perform basic set-up code, and demonstrate how to accomplish a task using our
-product.
+Usage examples are complete, actionable code blocks that demonstrate how to
+accomplish a specific task using MongoDB tools, drivers, or APIs. Usage
+examples are self-contained--they include the context needed to understand,
+run, and adapt the code in the code block (e.g. variable declarations).
 
 .. code-block:: csharp
 
@@ -88,20 +96,25 @@ product.
    // Create a new client and connect to the server
    var client = new MongoClient(connectionUri);
 
+.. _code-category-snippet:
 
 Snippets
 ````````
 
-We define snippets as ***a specific, atomic piece of code removed from any
-surrounding context.***
+Snippets are narrowly scoped code blocks that illustrate a specific concept or
+detail, typically as part of a broader explanation or tutorial. Unlike usage
+examples, they are informational, rather than actionable.
 
-.. PLACEHOLDER snippets taken out of the context of surrounding content don't really serve a purpose or make much sense.
+Snippets are intended to support other content, and they rely on the
+surrounding text or context to be meaningful. In some cases, a snippet may
+contain intentionally incomplete or invalid code for demonstration purposes
+(for example, a snippet showing all possible argument options for a command).
 
-.. note::
+Snippets fall into one of the following subtypes:
 
-   This guidance makes a distinction between the terms "code example" and
-   "code snippet." These terms are often used interchangeably. However,
-   "snippet" here has a specific definition as a type of code example.
+- **Non-MongoDB command:**: a command-line (CLI) command for any non-MongoDB
+  tooling (e.g. ``mkdir``, ``cd``, or ``npm``), often used in the context of a
+  tutorial.
 
 Snippets can fall into one of the following subcategories:
 
@@ -110,20 +123,39 @@ Snippets can fall into one of the following subcategories:
   page. For example, terminal commands like ``mkdir``, ``cd``, ``npm``, etc.
 
 .. code-block:: shell
+- **Syntax example**: an example of the syntax or structure for an API method,
+  an Atlas CLI command, a ``mongosh`` command, or other MongoDB tooling.
 
    dotnet run MyCompany.RAG.csproj
 
 - **Syntax example:** a tightly-scoped code block showing syntax for an API
   method, an Atlas CLI command, a ``mongosh`` command, or other MongoDB tooling.
 
 .. code-block:: text
+- **Return example**: an example of an object, such as a JSON blob or sample
+  document, returned after executing a corresponding piece of code. Commonly
+  included as the output of an ``io-code-block``.
 
    mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.net
 
 - **Return example**: a code block containing a JSON blob, example document, or
   other return object type. Use this snippet type to demonstrate what a user might expect from executing a piece of code.
 
 .. code-block:: text
+    A timeout occurred after 30000ms selecting a server using ...
+    Client view of cluster state is
+    {
+        ClusterId : "1",
+        State : "Disconnected",
+        Servers :
+        [{
+          ServerId: "{ ClusterId : 1, EndPoint : "localhost:27017" }",
+          EndPoint: "localhost:27017",
+          State: "Disconnected"
+        }]
+
+- **Configuration object example**: an example configuration object,
+  often represented in YAML or JSON, enumerating parameters and their types.
 
    A timeout occurred after 30000ms selecting a server using ...
    Client view of cluster state is
@@ -158,174 +190,79 @@ Snippets can fall into one of the following subcategories:
       name: atlas-default-backupschedule
       namespace: mongodb-atlas-system
 
+.. _code-category-sample-app:
 
 Sample Applications
-```````````````````
+~~~~~~~~~~~~~~~~~~~
 
-Sample applications are fully runnable applications that connect more discrete pieces
-of code. They may include error handling, framework integrations, or frontend user
-interface (UI) elements.
+Sample applications are complete, runnable programs that connect multiple
+discrete pieces of code. Sample apps may include error handling, framework
+integrations, or frontend UI elements.
 
 General Guidelines
 ------------------
 
-In general, our code examples should be simple enough to understand, complex
-enough to do something interesting, and provide value to our audience.
-
-As you're writing code examples, keep the following guidelines in mind:
-
-Treat Code Like Writing
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Apply the same writing guidelines in this Style Guide to your code examples,
-unless overruled by language-specific coding standards. For
-example, be consistent, avoid jargon, check for typos, write for accessibility
-and a global audience, etc.
-
-- Write code to be as clean and easy to understand as possible, even if it
-  isn't the most efficient or clever way to write it.
-- Provide examples that address problems our readers are trying to solve. Don't
-  illustrate obvious or contrived scenarios.
-
-Follow Best Practices
-~~~~~~~~~~~~~~~~~~~~~
-
-Our code examples should always follow generally accepted best practices. This
-is especially important because readers will copy and use our code examples
-outside of our Docs.
-
-- If code should *not* be copyable by users, ensure the ``:copyable:`` option is
-  ``false`` for the code block. To learn more about this markup, see
-  `Reference/Code Examples
-  <https://www.mongodb.com/docs/meta/reference/code-blocks/>`__.
-- Always follow best practices for security in your code and in any user
-  recommendations or instructions. For example, never hard code secrets or
-  credentials in an example.
+Our code examples should always follow generally accepted coding and security
+best practices, and all other applicable guidelines in this Style Guide that
+don't conflict with language-specific standards. Remember that users copy and
+use these code examples outside of our docs.
+
+Keep the following in mind as you write code examples:
+
+- Treat code like writing: Keep it simple, readable, and relevant to the task.
+- Write code that is easy to understand, even if it isn't the most efficient or
+  clever.
+- Introduce each code block with context.
+- List or note any prerequisites or code dependencies, especially in a tutorial.
+- Use descriptive names that clearly convey the purpose of the code element
+  (e.g. variable, function, class) or placeholder.
+- If a code is not intended to be directly used or adapted, such as a return
+  object example snippet, make sure the code block is not copyable. To learn
+  how to set the copyable option, see :ref:`code-block-reference`.
+- Don't write code examples for anti-patterns. If readers should be aware of an
+  anti-pattern or a commonly made mistake, communicate this clearly in the
+  surrounding text, an admonition, or an inline code comment.
 - If a code example is not production worthy in a significant way, communicate
-  this to readers clearly.
-- Don't write code examples that demonstrate the wrong way to do something. In
-  the rare instances that justify calling out how *not* to do something (eg, to
-  caution against a common bad practice or frequently made error), do so in the
-  page copy, in an admonition, or through inline code comments that can't be
-  mistaken for part of the code.
-
-Provide Context and Comments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Try to include enough information to ensure reader comprehension without
-stating the obvious or overwhelming with unnecessary details.
-
-- Introduce each code block with a high-level explanation of what the example
-  does, and why it's useful.
-- List specific prerequisites or dependencies.
-- Include code comments directly in the code block to explain or call out
-  important details, such as non-obvious logic or placeholder values that users
-  need to modify. Don't restate the code.
-
-.. TODO To learn more, see `TBD - Comments <PLACEHOLDER>`__.
-
-Test Every Example
-~~~~~~~~~~~~~~~~~~
-
-Non-working or incorrect examples negatively impact our credibility. Testing
-user-facing code examples ensures that they do what we say they do and work
-as expected. This is especially important for code that you didn't write
-yourself, such as an example provided by a SME or stakeholder.
-
-.. TODO update this section and the callout to DevDocs
-
-.. note::
-
-   For information or assistance with testing code examples, reach out to the
-   DevDocs team in the ``#ask-devdocs`` Slack channel or through the
-   ``@DevDocs`` GitHub team tag.
-
-- Writers: Always compile and test your code examples. Your code should pass as
-  written for the documentation.
-- Reviewers: Run all code examples as part of your review.
-
-For tutorials or content with multi-step examples, confirm that the code works
-by walking through every step exactly as written:
-
-- If there are any prerequisite steps or additional setup, begin at the assumed
-  starting point and complete the prerequisites exactly. Confirm that every step is correct, comprehensive, and necessary.
-- If you have to make changes or take additional steps to get an example to
-  work, make sure those details are reflected in the Doc.
+  this to readers through inline code comments *and* in the surrounding text.
+- Never use real customer data or hard code secrets in your code. If you're
+  unsure how to handle secrets in your code, reach out to the DevDocs team.
+- Use inline code comments to explain or call out important details, including:
+   - Non-obvious logic or intent. Don't restate the code.
+   - Omitted or truncated code.
+- Test every code example to ensure it works as intended:
+   - When writing or reviewing, run the code as it displays on the page.
+   - For tutorials or multi-step examples, begin at the starting point and
+     complete all steps exactly, including any prerequisites or setup. Don't
+     skip steps or assume they're correct.
+   - If you have to make changes or take additional steps to get an example to
+     work, make sure those details are reflected in the doc.
 
 Considerations for Robot Users, LLMs, and Other AI Models
 --------------------
 
 .. note::
 
-   This guidance uses phrases such as "robots *understand*" or "models *interpret* code" as convenient shorthand when discussing robot users. interpreted to mean that robot users have human-like reasoning capabilities.
-
-Robot users, such as LLMs (large language models), web crawlers, and other AI models, also consume our Docs content. However, robot users don't understand, think, or learn like a human user. They don't "read code" or "get context." Instead, they are predictive engines that pattern-match, tokenize, and respond based on probability and training data.
+   For any questions or help writing or testing code examples, reach
+   out to the ``@DevDocs`` team or use the ``#ask-devdocs`` Slack channel.
 
-To write code examples that robot users can understand quickly and interpret accurately, keep the following considerations in mind:
-
-- Code examples are as complete as possible. If there are omissions or truncations in an example, indicate the omissions clearly (for example, a code comment ``// imports omitted for brevity`` at the relevant line).
-- Ensure that transitions to code examples are obvious and explicit.
-- Never use inline code markup for code examples. Always use a code block directive, preferably as a shared include.
-- Use placeholder variables only when necessary, and ensure they are clearly commented or explained. Avoid placeholder variables that are not self-explanatory.
-- Do not insert explanations mid-block. Commentary should be before or after the code block, or as inline comments.
-
-
-
-- Code examples are self-contained and provide enough information for robot users to understand their purpose without relying on surrounding text or context.
-- code examples that provide enough information for robot users to understand their purpose without relying on surrounding text or context.
-- Code is consistently formatted and uses syntax-highlighted Markdown fences (eg., java).
-- Uses canonical imports, namespaces, and entry points (no unnecessary aliasing).
-- Placeholder variables are either avoided or clearly commented/explained.
-- Code includes concise, purposeful inline comments explaining intent or function.
-- File names and structure follow standard conventions (e.g., main.py, index.js, etc.).
-- Code blocks are single-language — no mixing languages inside one fence.
-- All code fences are properly closed to avoid truncating downstream content.
-
-
- Nice-to-Have: Improves Model Understanding and UX
-- Function/variable names are descriptive and realistic (connectToMongoDB() vs foo()).
-- Includes expected output blocks after commands or API calls when relevant.
-- Uses consistent multi-language tab structures for examples (e.g., JS/Python/Java).
-- Avoids over-abstraction — keeps just enough context to make examples meaningful.
-- Keeps logic explicit, even if it's less clever (avoid nested ternaries, dense one-liners).
-- Experimental, deprecated, or unsafe examples are clearly annotated with warnings.
-- Avoids mixing config, shell, and code in the same block — separate into clearly labeled sections.
-- Examples reflect the latest stable version of the tooling or API unless otherwise stated.
-
-
-When writing code examples, there are a few considerations to keep in mind for robot users that also consume our Docs content. Unlike human users, robot users cannot interpret meaning or context directly.
-
-
-
-.. collapsible::
-   :heading: Prerequisites
-   :sub_heading: Complete the previous steps in the tutorial and install dependencies
-   :expanded:
-
-   Body content goes here.
-
-.. AI models and web crawlers--such as LLMs, Googlebot, or machine translation engines--are referred to as robot users. They also consume our Docs content, so it's important to ensure that our Docs content, including code examples, effectively meets the needs of both human and robot users. Many of these considerations apply to code examples the same way they do to the rest of our Docs.
-
-.. For example, the following are applicable to both human and robot users:
-
-.. - Clear, descriptive headings and subheadings make it easier for users to understand the overall structure and purpose of the page and its elements, including code examples.
-.. - Enforcing a consistent, standard style and formatting, for page copy and code, ensures that users can parse the content easily and effectively.
-
-.. - Use clear and descriptive variable names, function names, and class names. Avoid using generic or ambiguous names that don't convey the purpose of the code. This helps robot users understand the code's functionality and intent.
-
-.. The considerations specific to robot users are related to how LLMs and other AI models interpret meaning, which is very limited compared to human users can. Robot users can't reliably understand or assume context or intent, extrapolate extract or assume meaning from the surrounding text or context.
-
-
-
-.. The following are considerations to help optimize code examples for robot users, especially LLMs:
-
-
-.. -
-
-.. - Provide context for every code example through introductory text and succinct code comments. See the
-..   `Provide Context and Comments <#provide-context-and-comments>`__ section
-..   above for more information.
-
-.. - For longer code examples (such as a single function), opt for keeping it as a single code block with explanatory inline comments as needed. Avoid splitting it into smaller blocks interspersed in the page text.
+Considerations for LLMs
+-----------------------
 
-.. .. TODO Add explanatory image
+The robot users (such as LLMs and other AI models) that consume our docs are unable to infer meaning or intent from context.
+
+To ensure that our code examples are robot friendly, keep the following in mind:
+
+- Write code examples that are self-contained and provide enough information
+  for robot users to understand their purpose without relying on surrounding
+  text or context.
+- Don't split code into multiple pieces.
+- Use inline comments to clearly mark any omitted or truncated sections.
+- Explain intent, purpose, or expected code behavior through surrounding text *and* inline comments.
+- File names, file structure, and code follows idiomatic, canonical patterns
+  (e.g. ``main()``, ``index.js``, ``connect()``). Avoid unnecessary aliasing or
+  non-standard structures unless explained clearly.
+- Use consistent, descriptive names that indicate purpose. Avoid vague names
+  like ``foo``, ``x``, or ``doStuff()``.
+- Make sure the correct language is specified for every code block.
+- Clearly mark placeholders and explain how to replace them through an inline
+  comment.