Add brittleness information to id()/elementId() functions (#1035)

Author: JPryce-Aklundh

modules/ROOT/pages/clauses/order-by.adoc

@@ -114,12 +114,9 @@ The nodes are returned, sorted by their internal ID.
 |===
 
 [NOTE]
-====
-Keep in mind that Neo4j reuses its internal IDs when nodes and relationships are deleted.
-This means that applications using, and relying on, internal Neo4j IDs, are brittle or at risk of making mistakes.
-It is therefore recommended to use application-generated IDs instead.
-====
-
+Neo4j reuses its internal IDs when nodes and relationships are deleted.
+Applications relying on internal Neo4j IDs are, as a result, brittle and can be inaccurate.
+It is recommended to use application-generated IDs instead.
 
 [[order-nodes-by-expression]]
 == Order nodes by expression

modules/ROOT/pages/functions/scalar.adoc

@@ -6,7 +6,6 @@
 
 Scalar functions return a single value.
 
-
 [IMPORTANT]
 ====
 The `length()` and `size()` functions are quite similar, and so it is important to take note of the difference.
@@ -191,8 +190,8 @@ However, no guarantees are given regarding the order of the returned ID values o
 Outside of the scope of a single transaction, no guarantees are given about the mapping between ID values and elements.
 
 . Neo4j reuses its internal IDs when nodes and relationships are deleted.
-This means that applications using, and relying on internal Neo4j IDs, are brittle or at risk of making mistakes.
-It is therefore recommended to rather use application-generated IDs.
+Applications relying on internal Neo4j IDs are, as a result, brittle and can be inaccurate.
+It is therefore recommended to use application-generated IDs.
 
 
 .Considerations
@@ -361,22 +360,29 @@ It is recommended to use xref:functions/scalar.adoc#functions-elementid[`element
 
 |===
 
-The function `id()` returns a node or a relationship identifier, unique by an object type and a database.
+There are important considerations to bear in mind when using `id()`:
+
+. The function `id()` returns a node or a relationship identifier, unique by an object type and a database.
 Therefore, `id()` can return the same value for both nodes and relationships in the same database.
 
-Neo4j implements the id so that every node and relationship in a database has an identifier.
+. Neo4j implements the ID so that every node and relationship in a database has an identifier.
 The identifier for a node or relationship is guaranteed to be unique among other nodes' and relationships' identifiers in the same database, within the scope of a single transaction.
 
+. Neo4j reuses its internal IDs when nodes and relationships are deleted.
+Applications relying on internal Neo4j IDs are, as a result, brittle and can be inaccurate.
+It is therefore recommended to use application-generated IDs instead.
+
+
 [NOTE]
 ====
 On a link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/composite-databases/concepts/[composite database], the `id()` function should be used with caution.
 It is recommended to use xref:functions/scalar.adoc#functions-elementid[`elementId()`] instead. 
 
-When called in database-specific subqueries, the resulting id value for a node or relationship is local to that database.
-The local id for nodes or relationships from different databases may be the same.
+When called in database-specific subqueries, the resulting ID value for a node or relationship is local to that database.
+The local ID for nodes or relationships from different databases may be the same.
 
-When called from the root context of a query, the resulting value is an extended id for the node or relationship.
-The extended id is likely different from the local id for the same node or relationship.
+When called from the root context of a query, the resulting value is an extended ID for the node or relationship.
+The extended ID is likely different from the local ID for the same node or relationship.
 ====