doc: update conventions with repl examples and function (in|out)puts

doc/README.md

@@ -184,12 +184,67 @@ In that case, please open an issue about the particular documentation convention
  }
  ```
 
-- Use [definition lists](#definition-lists) to document function arguments, and the attributes of such arguments. For example:
+- When showing inputs/outputs of any [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop), such as a shell or the Nix REPL, use a format as you'd see in the REPL, while trying to visually separate inputs from outputs.
+ This means that for a shell, you should use a format like the following:
+ ```shell
+ $ nix-build -A hello '<nixpkgs>' \
+ --option require-sigs false \
+ --option trusted-substituters file:///tmp/hello-cache \
+ --option substituters file:///tmp/hello-cache
+ /nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1
+ ```
+ Note how the input is preceded by `$` on the first line and indented on subsequent lines, and how the output is provided as you'd see on the shell.
+
+ For the Nix REPL, you should use a format like the following:
+ ```shell
+ nix-repl> builtins.attrNames { a = 1; b = 2; }
+ [ "a" "b" ]
+ ```
+ Note how the input is preceded by `nix-repl>` and the output is provided as you'd see on the Nix REPL.
+
+- When documenting functions or anything that has inputs/outputs and example usage, use nested headings to clearly separate inputs, outputs, and examples.
+ Keep examples as the last nested heading, and link to the examples wherever applicable in the documentation.
+
+ The content of the nested headings is still up to the writer.
+ The purpose of this convention is to provide a familiar structure for navigating the manual, so any reader can expect to find content related to inputs in an "inputs" heading, examples in an "examples" heading, and so on.
+ An example:
+ ```
+ ## buildImage
+
+ Some explanation about the function here.
+ Describe a particular scenario, and point to [](#ex-dockerTools-buildImage), which is an example demonstrating it.
+
+ ### Inputs
+
+ Documentation for the inputs of `buildImage`.
+ Perhaps even point to [](#ex-dockerTools-buildImage) again when talking about something specifically linked to it.
+
+ ### Passthru outputs
+
+ Documentation for any passthru outputs of `buildImage`.
+
+ ### Examples
+
+ Note that this is the last nested heading in the `buildImage` section.
+
+ :::{.example #ex-dockerTools-buildImage}
+
+ # Using `buildImage`
+
+ Example of how to use `buildImage` goes here.
+
+ :::
+ ```
+
+- Use [definition lists](#definition-lists) to document function arguments, the attributes of such arguments, or any other attribute sets in general. For example:
 
  ```markdown
  # pkgs.coolFunction
 
  Description of what `coolFunction` does.
+
+ ## Inputs
+
  `coolFunction` expects a single argument which should be an attribute set, with the following possible attributes:
 
  `name`