Improve documentation

docs/mysql-admutils-compatibility.md

@@ -1,6 +1,6 @@
 # Compatibility mode with [mysql-admutils](https://git.pvv.ntnu.no/Projects/mysql-admutils)
 
-If you enable the feature flag `mysql-admutils-compatibility` (enabled by default for now), the output directory will contain two symlinks to the `musl` binary: `mysql-dbadm` and `mysql-useradm`. When invoked through these symlinks, the binary will react to its `argv[0]` and behave accordingly. These modes strive to behave as similar as possible to the original programs.
+If you enable the `mysql-admutils-compatibility` feature flag when [compiling][compiling] (enabled by default for now), the output directory will contain two symlinks to the `muscl` binary: `mysql-dbadm` and `mysql-useradm`. When you run either of the symlinks, the program will enter a compatibility mode that mimics the behaviour of the corresponding program from the `mysql-admutils` package. These tools try to replicate the behaviour of the original programs as closely as possible.
 
 ```bash
 cargo build
@@ -8,21 +8,32 @@ cargo build
 ./target/debug/mysql-useradm --help
 ```
 
-These symlinks are also included in the deb packages.
+These symlinks are also included in the deb packages by default.
 
 ### Known deviations from `mysql-admutils`' behaviour
 
+There are some differences between the original programs and the compatibility mode in `muscl`.
+The known ones are:
+
 - `--help` output is formatted by clap in a different style.
-- `mysql-dbadm edit-perm` uses the new privilege editor implementation. Replicating
-  the old behaviour
-  there shoulnd't have been any (or at least very few) scripts relying on the old
-  command API or behavior.
-- The new tools use the new implementation to find it's configuration file, and uses the
-  new configuration format. See the example config and installation instructions for more
-  information about how to configure the software.
-- The order in which input is validated (e.g. whether you own a user, whether the
-  contains illegal characters, whether the user does or does not exist) might be different
-  from the original program, leading to the same command reporting different errors.
-- Arguments are de-duplicated, meaning that if you run something like
+- `mysql-dbadm edit-perm` uses the new privilege editor implementation. The formatting that
+  was used in `mysql-admutils` is no longer present. However, since the editor is purely an
+  interactive tool, there shouldn't have been any scripts relying on the old formatting.
+- The configuration file is shared for all variants of the program, and `muscl` will use
+  its new logic to look for and parse this file. See the example config and
+  [installation instructions][installation-instructions] for more information about how to
+  configure the software.
+- The order in which input is validated might be differ from the original
+  (e.g. database ownership checks, invalid character checks, existence checks, ...).
+  This means that running the exact same command might lead to different error messages.
+- Command-line arguments are de-duplicated. For example, if the user runs
   `mysql-dbadm create user_db1 user_db2 user_db1`, the program will only try to create
-  the `user_db1` once. The old program would attempt to create it twice, failing the second time.
+  the `user_db1` once. The old program would have attempted to create it twice,
+  failing the second attempt.
+
+One detail that might be considered a difference but, is that the compatibility mode supports
+command line completions when the user presses tab. This is not a feature of the original programs,
+but it does not change any of the previous behaviour either.
+
+[compiling]: ./compiling.md
+[installation-instructions]: ./installation.md