MONGOID-5161 revise dots and dollars documentation again (#5191)

* MONGOID-5161 revise dots and dollars documentation again

* suggested wording

Co-authored-by: Oleg Pudeyev <[email protected]>

Author: p-mongo

docs/reference/fields.txt

@@ -1320,41 +1320,26 @@ you can include the short versions of the modules.
 Field Names with Dots/Periods (``.``) and Dollar Signs (``$``)
 ==============================================================
 
-MongoDB query language (MQL) generally uses the dot/period character (``.``)
-to separate field names in a field path that traverses embedded documents, and
-the dollar character (``$``) for operators. It is possible to utilize field
-names containing the dot and dollar characters, however it is recommended to
-avoid these characters for ease of querying.
-
-MongoDB 5.0 adds `special operators
-<https://mongodb.com/docs/manual/core/dot-dollar-considerations/#std-label-crud-concepts-dot-dollar-considerations>`_
-for querying and modifying documents using field names containing dots and
-dollars. Previous MongoDB versions do not provide a mechanism for querying
-documents on fields whose names contain dots and dollars, though such documents
-can be retrieved verbatim (once they are matched using some other strategy).
-
-Mongoid provides its own DSL for querying MongoDB and, unlike MongoDB 5.0,
-Mongoid does not yet provide any facilities for querying documents using
-field names containing dots and dollars. It is possible to query such documents
-using MQL, but not via most Mongoid DSL methods. Additionally, there is
-other code in Mongoid that assumes that the dot (``.``) separates path
-components which may misbehave should a document contain a field with dots
-in its name.
-
-Historically, MongoDB drivers prohibited inserting documents with field names
-containing dots and dollars, since such documents couldn't be queried via
-those field names. This prohibition is now being lifted due to the new
-operators introduced with MongoDB 5.0; however, the required changes in the
-Ruby driver `have not yet been implemented
-<https://jira.mongodb.org/browse/RUBY-2528>`_. By virtue of using the Ruby
-driver to interact with the database, this prohibition on inserting documents
-with field names containing dots and dollars also applies to Mongoid.
-Thus, while both the Ruby driver and Mongoid permit querying documents that
-have been inserted using other mechanisms by field names containing dots and
-dollars, there is presently no possibility to insert such documents using
-either Ruby driver or Mongoid.
-
-To summarize, field names containing dots and dollars have limited support in
-Mongoid, the Ruby MongoDB driver and MongoDB server. Such field names should
-only be used when interfacing with software that already uses these names,
-and should be avoided for new development.
+Using dots/periods (``.``) in fields names and starting a field name with
+a dollar sign (``$``) is not recommended, as Mongoid provides limited support
+for retrieving and operating on the documents stored in those fields.
+
+Both Mongoid and MongoDB query language (MQL) generally use the dot/period
+character (``.``) to separate field names in a field path that traverses
+embedded documents, and words beginning with the dollar sign (``$``) as
+operators. MongoDB provides `limited support
+<https://www.mongodb.com/docs/manual/core/dot-dollar-considerations/#std-label-crud-concepts-dot-dollar-considerations>`_
+for using field names containing dots and starting with the dollar sign
+for interoperability with other software,
+however, due to this support being confined to specific operators
+(e.g. :manual:`getField </reference/operator/aggregation/getField/>`,
+:manual:`setField </reference/operator/aggregation/setField/>`) and
+requiring the usage of the aggregation pipeline for both queries and updates,
+applications should avoid using dots in field names and starting field names
+with the dollar sign if possible.
+
+The Ruby driver `currently prohibits
+<https://jira.mongodb.org/browse/RUBY-2528>`_ inserting documents whose
+field names contain dots or begin with the dollar sign. However, if such
+documents are inserted using other software, Mongoid and the Ruby driver
+provide limited support for retrieving and operating on these documents.