Fix build fail error

Author: cbullinger

source/style-guide/code-example-guidelines.txt

@@ -29,51 +29,35 @@ 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.
 
-- Use code-block directives for all code examples. Code blocks are visually
-  distinct, easier to read, and better interpreted by robot users (such as
+- Use code-block directives for all code examples. A code block is a visually
+  and functionally distinct page element that defines and displays its content
+  as code. It is 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).
+- Do not use inline code markup to write code examples. Use
+  inline code to format code-related references within text in ``monospace``
+  (such as method names).
 
 1. Inline Code
 #. Code Block
 
 .. figure:: /images/code-inline-vs-block.png
    :alt: Comparison of rendered inline code and a code block
 
-Inline Code
-```````````
-
-Inline code (sometimes referred to as "code in text") refers to code-related
-words or phrases, such as a method name in a sentence, rendered in
-``monospace``. To learn more about when to use ``monospace`` text, see
-`Text Formatting <https://www.mongodb.com/docs/meta/style-guide/style/text-formatting/#text-formatting>`__.
-
-Inline code is not considered a type of code example.
-Inline code is not a code block, and it does not have the same formatting or functionality as a code block. Unlike code blocks elements, inline code isn't a different element. It is still paragraph text, similar to text formatted with **bold**  or *italic* markup. To learn more, see `Inline Markup <https://www.mongodb.com/docs/meta/style-guide/markup/inline/#inline-markup>`__.
-
-Code Block
-``````````
-
-Code examples are always formatted in code blocks, which are distinct from the
-surrounding text. Code blocks support additional functionality, such as syntax
-highlighting or a caption label. For more information on the rST directives
-used to render a code block, see
-`Code Examples <https://www.mongodb.com/docs/meta/reference/code-blocks/>`__.
-
 Types of Code Examples
 ----------------------
 
-.. NOTE related page: `Reference/Code Examples <https://www.mongodb.com/docs/meta/reference/code-blocks/`__
+.. note::
 
-   Although "code example" and "snippet" are often used interchangeably, this guidance uses "snippet" to mean a context-less block of code.
+   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:
 
 - :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.
+  concept or detail in the context of a larger example, tutorial, or reference
+  page.
 - :ref:`Sample Applications <code-category-sample-app>`: Runnable applications
   demonstrating broader use cases.
 
@@ -82,10 +66,11 @@ We categorize code examples into the following types:
 Usage Examples
 ~~~~~~~~~~~~~~
 
-Usage examples are complete, actionable code blocks that demonstrate how to
+Usage examples are self-contained, actionable code blocks that show 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).
+examples include enough context to understand, run, and adapt the code
+contained in the code block (for example, the code includes any variable
+declarations).
 
 .. code-block:: csharp
 
@@ -99,49 +84,40 @@ run, and adapt the code in the code block (e.g. variable declarations).
 .. _code-category-snippet:
 
 Snippets
-````````
+~~~~~~~~
 
-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.
+Snippets are narrowly scoped code blocks that help explain a specific concept
+or detail. They are typically used as part of a broader explanation or
+tutorial, and are often meaningful only within that context.
 
-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).
+Snippets are intended to provide information. They aren't required to be valid
+or runnable code. In some cases, a snippets may contain intentionally
+incomplete or incorrect code for demonstration purposes (for example, a snippet
+showing all possible argument options for a command).
 
 Snippets fall into one of the following subtypes:
 
 - **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:
+  .. code-block:: shell
 
-- **Non-MongoDB command:** code blocks containing command-line commands for
-  non-MongoDB tooling, typically in the context of a larger tutorial-style
-  page. For example, terminal commands like ``mkdir``, ``cd``, ``npm``, etc.
+    dotnet run MyCompany.RAG.csproj
 
-.. 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
+  .. code-block:: text
 
-- **Syntax example:** a tightly-scoped code block showing syntax for an API
-  method, an Atlas CLI command, a ``mongosh`` command, or other MongoDB tooling.
+    mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.net
 
-.. 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
 
-.. code-block:: text
     A timeout occurred after 30000ms selecting a server using ...
     Client view of cluster state is
     {
@@ -157,38 +133,16 @@ Snippets can fall into one of the following subcategories:
 - **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
-   {
-      ClusterId : "1",
-      Type : "Unknown",
-      State : "Disconnected",
-      Servers :
-      [{
-         ServerId: "{ ClusterId : 1, EndPoint : "Unspecified/localhost:27017" }",
-         EndPoint: "Unspecified/localhost:27017",
-         ReasonChanged: "Heartbeat",
-         State: "Disconnected",
-         ServerVersion: ,
-         TopologyVersion: ,
-         Type: "Unknown",
-         HeartbeatException: "<exception details>"
-      }]
-
-
-- **Configuration object example**: a code block showing an example object,
-  often represented in YAML or JSON, enumerating parameters and their types.
+  .. code-block:: ini
 
-.. code-block:: ini
-
-   apiVersion: atlas.mongodb.com/v1
-   kind: AtlasDeployment
-   metadata:
-   name: my-atlas-cluster
-   spec:
-   backupRef:
-      name: atlas-default-backupschedule
-      namespace: mongodb-atlas-system
+    apiVersion: atlas.mongodb.com/v1
+    kind: AtlasDeployment
+    metadata:
+    name: my-atlas-cluster
+    spec:
+    backupRef:
+        name: atlas-default-backupschedule
+        namespace: mongodb-atlas-system
 
 .. _code-category-sample-app:
 
@@ -212,16 +166,17 @@ 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.
+- Introduce each code block with context, as you would a list or table.
+- Include any prerequisites or code dependencies needed for a piece of code.
 - 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.
+- Don't write code examples for anti-patterns. If you need to note an
+  anti-pattern or a commonly made mistake, use the
+  surrounding text, an admonition, or an inline code comment, and ensure that
+  it cannot be mistaken for a recommended pattern.
 - If a code example is not production worthy in a significant way, communicate
   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
@@ -237,32 +192,32 @@ Keep the following in mind as you write code examples:
    - 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::
 
-   For any questions or help writing or testing code examples, reach
+   For any questions or for help writing or testing code examples, reach
    out to the ``@DevDocs`` team or use the ``#ask-devdocs`` Slack channel.
 
 Considerations for LLMs
 -----------------------
 
-The robot users (such as LLMs and other AI models) that consume our docs are unable to infer meaning or intent from context.
+Unlike human readers, the robots that consume our docs (such as LLMs and other
+AI models) can't infer meaning or intent from context. Robot users struggle
+with ambiguity, unclear boundaries, partial or implicit information, and
+non-standard patterns.
 
 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
+- Prefer atomic code examples: code should be as self-contained and self-descriptive as possible so that robot users can understand the code more easily.
+- Explain intent, purpose, or expected code behavior through surrounding text
+  *and* inline comments.
+- Don't interrupt a single code block with text explanations. Keep explanatory
+  text before or after the code block, and use inline comments for explanations
+  within the code block.
+- Prefer conventional file structure, names, and 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.
+- Clearly mark and explain any placeholders, omissions, or truncated code
+  through inline comments.