From 3f90fb3abe18c8b6111a6d87adc71114c90b4559 Mon Sep 17 00:00:00 2001
From: Jeff Allen <jeffrey.allen@10gen.com>
Date: Tue, 23 Jan 2024 16:32:51 -0500
Subject: [PATCH] (DOCSP-33844): Fix inaccuracy on tailable cursor doc (#5922)
 (#5940)

* (DOCSP-33844): Fix inaccuracy on tailable cursor doc

* edit

* IA template adjustments

* add period

* avoid 'dead'

* reorder

* typo

* wording

* review edits

* wording adjustment
---
 source/core/tailable-cursors.txt | 70 ++++++++++++++++++++------------
 1 file changed, 43 insertions(+), 27 deletions(-)

diff --git a/source/core/tailable-cursors.txt b/source/core/tailable-cursors.txt
index fdefbe8a6f7..e442908eafa 100644
--- a/source/core/tailable-cursors.txt
+++ b/source/core/tailable-cursors.txt
@@ -6,15 +6,27 @@ Tailable Cursors
 
 .. default-domain:: mongodb
 
-By default, MongoDB will automatically close a cursor when the client
-has exhausted all results in the cursor. However, for :doc:`capped
-collections </core/capped-collections>` you may use a *Tailable
-Cursor* that remains open after the client exhausts the results in the
+.. facet::
+   :name: genre
+   :values: reference
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+By default, MongoDB automatically closes a cursor when the client
+exhausts all results in the cursor. However, for :ref:`capped
+collections <manual-capped-collection>` you can use a :term:`tailable
+cursor` that remains open after the client exhausts the results in the
 initial cursor. Tailable cursors are conceptually equivalent to the
-``tail`` Unix command with the ``-f`` option (i.e. with "follow"
-mode). After clients insert new additional documents into a capped
-collection, the tailable cursor will continue to retrieve
-documents.
+``tail`` Unix command with the ``-f`` option ("follow" mode). After
+clients insert additional documents into a capped collection, the
+tailable cursor continues to retrieve documents.
+
+Use Cases
+---------
 
 Use tailable cursors on capped collections that have high write
 volumes where indexes aren't practical. For instance,
@@ -23,34 +35,38 @@ tail the primary's :term:`oplog`.
 
 .. note::
 
-   If your query is on an indexed field, do not use tailable cursors,
-   but instead, use a regular cursor. Keep track of the last value of
-   the indexed field returned by the query. To retrieve the newly
-   added documents, query the collection again using the last value of
-   the indexed field in the query criteria, as in the following
-   example:
+   If your query is on an indexed field, use a regular cursor instead of
+   a tailable cursor. Keep track of the last value of the indexed field
+   returned by the query. To retrieve the newly added documents, query
+   the collection again using the last value of the indexed field in the
+   query criteria. For example:
 
    .. code-block:: javascript
 
       db.<collection>.find( { indexedField: { $gt: <lastvalue> } } )
 
-Consider the following behaviors related to tailable cursors:
+Get Started
+-----------
 
-- Tailable cursors do not use indexes and return documents in
-  :term:`natural order`.
+To create a tailable cursor in :binary:`mongosh`, see
+:method:`cursor.tailable()`.
 
-- Because tailable cursors do not use indexes, the initial scan for the
-  query may be expensive; but, after initially exhausting the cursor,
-  subsequent retrievals of the newly added documents are inexpensive.
+To see tailable cursor methods for your driver, see your :driver:`driver
+documentation </>`.
 
-- Tailable cursors may become *dead*, or invalid, if either:
+Behavior
+--------
 
-  - the query returns no match.
+Consider the following behaviors related to tailable cursors:
 
-  - the cursor returns the document at the "end" of the collection and
-    then the application deletes that document.
+- Tailable cursors do not use indexes. They return documents in
+  :term:`natural order`.
 
-  A *dead* cursor has an ID of ``0``.
+- Because tailable cursors do not use indexes, the initial scan for the
+  query may be expensive. After initially exhausting the cursor,
+  subsequent retrievals of the newly added documents are inexpensive.
 
-See your :driver:`driver documentation </>` for the
-driver-specific method to specify the tailable cursor.
+- A tailable cursor can become invalid if the data at its current
+  position is overwritten by new data. For example, this can happen if
+  the speed of data insertion is faster than the speed of cursor
+  iteration.