diff --git a/operators/entries.md b/operators/entries.md
index b70b2607..232ff4df 100644
--- a/operators/entries.md
+++ b/operators/entries.md
@@ -2,6 +2,8 @@
 
 Similar to the same named functions in `jq` these functions convert to/from an object and an array of key-value pairs. This is most useful for performing operations on keys of maps.
 
+Use `with_entries(op)` as a syntatic sugar for doing `to_entries | op | from_entries`.
+
 ## to_entries Map
 Given a sample.yml file of:
 ```yaml
@@ -101,6 +103,28 @@ KEY_a: 1
 KEY_b: 2
 ```
 
+## Use with_entries to update keys recursively
+We use (.. | select(tag="map")) to find all the maps in the doc, then |= to update each one of those maps. In the update, with_entries is used.
+
+Given a sample.yml file of:
+```yaml
+a: 1
+b:
+  b_a: nested
+  b_b: thing
+```
+then
+```bash
+yq '(.. | select(tag=="!!map")) |= with_entries(.key |= "KEY_" + .)' sample.yml
+```
+will output
+```yaml
+KEY_a: 1
+KEY_b:
+  KEY_b_a: nested
+  KEY_b_b: thing
+```
+
 ## Custom sort map keys
 Use to_entries to convert to an array of key/value pairs, sort the array using sort/sort_by/etc, and convert it back.
 
diff --git a/operators/sort-keys.md b/operators/sort-keys.md
index fb8e86ac..e0055b53 100644
--- a/operators/sort-keys.md
+++ b/operators/sort-keys.md
@@ -12,8 +12,8 @@ diff file1.yml file2.yml
 
 Note that `yq` does not yet consider anchors when sorting by keys - this may result in invalid yaml documents if you are using merge anchors.
 
-For more advanced sorting, using `to_entries` to convert the map to an array, then sort/process the array as you like (e.g. using `sort_by`) and convert back to a map using `from_entries`.
-See [here](https://mikefarah.gitbook.io/yq/operators/entries#custom-sort-map-keys) for an example. 
+For more advanced sorting, you can use the [sort_by](https://mikefarah.gitbook.io/yq/operators/sort) function on a map, and give it a custom function like `sort_by(key | downcase)`.
+
 
 ## Sort keys of map
 Given a sample.yml file of:
diff --git a/operators/sort.md b/operators/sort.md
index 72a17305..73fd24da 100644
--- a/operators/sort.md
+++ b/operators/sort.md
@@ -109,6 +109,46 @@ cool:
   - c: banana
 ```
 
+## Sort a map
+Sorting a map, by default this will sort by the values
+
+Given a sample.yml file of:
+```yaml
+y: b
+z: a
+x: c
+```
+then
+```bash
+yq 'sort' sample.yml
+```
+will output
+```yaml
+z: a
+y: b
+x: c
+```
+
+## Sort a map by keys
+Use sort_by to sort a map using a custom function
+
+Given a sample.yml file of:
+```yaml
+Y: b
+z: a
+x: c
+```
+then
+```bash
+yq 'sort_by(key | downcase)' sample.yml
+```
+will output
+```yaml
+x: c
+Y: b
+z: a
+```
+
 ## Sort is stable
 Note the order of the elements in unchanged when equal in sorting.
 
diff --git a/usage/properties.md b/usage/properties.md
index 50217032..0432e4ab 100644
--- a/usage/properties.md
+++ b/usage/properties.md
@@ -71,7 +71,7 @@ person.food[0] = pizza
 ```
 
 ## Encode properties - custom separator
-Use the --properties-customer-separator flag to specify your own key/value separator.
+Use the --properties-separator flag to specify your own key/value separator.
 
 Given a sample.yml file of:
 ```yaml
@@ -89,7 +89,7 @@ emptyMap: []
 ```
 then
 ```bash
-yq -o=props --properties-customer-separator=" :@ " sample.yml
+yq -o=props --properties-separator=" :@ " sample.yml
 ```
 will output
 ```properties