From cb23ff8e5507a6ed442327694de109eca4affd02 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 27 Nov 2023 21:51:02 +0100
Subject: [PATCH] docs: rewrite section on setting user id

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 docs/reference/run.md | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/docs/reference/run.md b/docs/reference/run.md
index adf537a4df48..ebe5e4134093 100644
--- a/docs/reference/run.md
+++ b/docs/reference/run.md
@@ -1208,21 +1208,25 @@ The health status is also displayed in the `docker ps` output.
 
 ### User
 
-`root` (id = 0) is the default user within a container. The image developer can
-create additional users. Those users are accessible by name.  When passing a numeric
-ID, the user does not have to exist in the container.
+The default user within a container is `root` (id = 0). You can set a default
+user to run the first process with the Dockerfile `USER` instruction. When
+starting a container, you can override the `USER` instruction by passing the
+`-u` option.
 
-The developer can set a default user to run the first process with the
-Dockerfile `USER` instruction. When starting a container, the operator can override
-the `USER` instruction by passing the `-u` option.
+```text
+-u="", --user="": Sets the username or UID used and optionally the groupname or GID for the specified command.
+```
 
-    -u="", --user="": Sets the username or UID used and optionally the groupname or GID for the specified command.
+The followings examples are all valid:
 
-    The followings examples are all valid:
-    --user=[ user | user:group | uid | uid:gid | user:gid | uid:group ]
+```text
+--user=[ user | user:group | uid | uid:gid | user:gid | uid:group ]
+```
 
-> **Note:** if you pass a numeric uid, it must be in the range of 0-2147483647.
-> If you pass a username, the user must exist in the container.
+> **Note**
+>
+> If you pass a numeric user ID, it must be in the range of 0-2147483647. If
+> you pass a username, the user must exist in the container.
 
 ### Working directory