From d0d0b9a748051e1957c5ba332b9eb74112c15570 Mon Sep 17 00:00:00 2001
From: Robert Hensing <roberth@users.noreply.github.com>
Date: Tue, 28 Feb 2023 16:28:54 +0100
Subject: [PATCH] doc/cli-guideline: Improve examples

Turns out that the settings themselves have a bad data model anyway, so we cut that. They do still occur in the first example, but not in focus.
---
 doc/manual/src/contributing/cli-guideline.md | 74 ++++++++------------
 1 file changed, 29 insertions(+), 45 deletions(-)

diff --git a/doc/manual/src/contributing/cli-guideline.md b/doc/manual/src/contributing/cli-guideline.md
index 3e56d9037..e53d2d178 100644
--- a/doc/manual/src/contributing/cli-guideline.md
+++ b/doc/manual/src/contributing/cli-guideline.md
@@ -425,65 +425,49 @@ This leads to the following guidelines:
 
 ### Examples
 
-```javascript
-// bad: all keys must be assumed to be store implementations
+
+This is bad, because all keys must be assumed to be store implementations:
+
+```json
 {
   "local": { ... },
   "remote": { ... },
   "http": { ... }
 }
-// good: extensible and a little bit self-documenting.
+```
+
+This is good, because the it is extensible at the root, and is somewhat self-documenting:
+
+```json
 {
   "storeTypes": { "local": { ... }, ... },
-  // While the dictionary of store types seemed like a complete response,
-  // this little bit of info tells the consumer how to proceed if a store type
-  // is missing. It's not always easy to predict how something will be used, so
-  // let's keep it open.
   "pluginSupport": true
 }
 ```
 
-```javascript
-// bad: a store type can only hold configuration items
-{
-  "storeTypes": {
-    "Local Daemon Store": {
-      "max-connections": {
-        "defaultValue": 1
-        "value": 1
-      },
-      "trusted": {
-        "defaultValue": false,
-        "value": true
-      },
-      ...
-    }
-  }
-}
-// good: a store type can be extended with other metadata, such as its URI scheme
-{
-  "storeTypes": {
-    "Local Daemon Store": {
-      "uriScheme": "daemon",
-      "settings": {
-        "max-connections": {
-          "defaultValue": 1
-          "value": 1
-        },
-        ...
-      },
-    ...
-  },
-  ...
-}
+While the dictionary of store types seems like a very complete response at first, a use case may arise that warrants returning additional information.
+For example, the presence of plugin support may be crucial information for a client to proceed when their desired store type is missing.
+
+
+
+The following representation is bad because it is not extensible:
+
+```json
+{ "outputs": [ "out" "bin" ] }
 ```
 
-```javascript
-// bad: not extensible
-{ "outputs": [ "out" "bin" ] }
-// bad: order matters but is lost, as many JSON parsers don't preserve item order.
+However, simply converting everything to records is not enough, because the order of outputs must be preserved:
+
+```json
 { "outputs": { "bin": {}, "out": {} } }
-// good:
+```
+
+The first item is the default output. Deriving this information from the outputs ordering is not great, but this is how Nix currently happens to work.
+While it is possible for a JSON parser to preserve the order of fields, we can not rely on this capability to be present in all JSON libraries.
+
+This representation is extensible and preserves the ordering:
+
+```json
 { "outputs": [ { "outputName": "out" }, { "outputName": "bin" } ] }
 ```