diff --git a/doc/getting-started.md b/doc/getting-started.md
index 2e945b8..aacef75 100644
--- a/doc/getting-started.md
+++ b/doc/getting-started.md
@@ -14,39 +14,31 @@ channels from a ZNC config file:
 
 ## Client side
 
-soju can operate in two different modes: multi upstream and single upstream.
+### Client supporting `soju.im/bouncer-networks`
 
-### Single upstream mode
+If your are using a client supporting the `soju.im/bouncer-networks` IRC
+extension (see the [client list]), then you can just connect to soju with your
+username and password.
 
-In this mode, 1 upstream connection to a irc server = 1 connection to your soju
-bouncer.
+If your client doesn't provide a UI to manage IRC networks, you can talk to
+`BouncerServ`. See the [man page] or use `/msg BouncerServ help`.
 
-The easiest and fastest way to use this is to specify the address of the server
-in your username in your client configuration. For example to connect to
-Libera Chat, your username will be: `<soju username>/irc.libera.chat`. Also set
-your soju password in the password field of your client configuration.
+### Other clients
+
+You will need to setup one separate server in your client for each server you
+want soju to connect to.
+
+The easiest way to get started is to specify the IRC server address directly in
+the username in the client configuration. For example to connect to Libera Chat,
+your username will be: `<soju username>/irc.libera.chat`. Also set your soju
+password in the password field of your client configuration.
 
 This will autoconfigure soju by adding a network with the address
 `irc.libera.chat` and then autoconnect to it. You will now be able to join
 any channel like you would normally do.
 
-### Multi upstream mode
+For more advanced configuration options, you can talk to `BouncerServ`. See the
+[man page] or use `/msg BouncerServ help`.
 
-In this mode, a single connection to your soju bouncer can handle multiple
-upstream connections. You will need to manually configure each upstream
-connection using the the special `BouncerServ` user.
-
-Connect to your soju server by specifying `<soju username>/*` in the username
-field in your client and your password in the password field.
-
-You should now be able to send private messages to the `BouncerServ`. You can
-send it commands to configure soju. Create new networks:
-
-    /msg BouncerServ network create -addr irc.libera.chat -name libera
-    /msg BouncerServ network create -addr irc.rizon.net -name rizon
-
-You will now be able to join channels on these networks by specifying their
-name:
-
-    /join #soju/libera
-    /join #somechannel/rizon
+[man page]: https://soju.im/doc/soju.1.html#IRC_SERVICE
+[client list]: ../contrib/clients.md
diff --git a/doc/multi-upstream.md b/doc/multi-upstream.md
new file mode 100644
index 0000000..957d57e
--- /dev/null
+++ b/doc/multi-upstream.md
@@ -0,0 +1,29 @@
+# Multi-upstream mode
+
+When setting up a new IRC client which doesn't support the
+`soju.im/bouncer-networks` extension, one needs to configure as many servers as
+there are networks configured in soju. Whenever a network is added or removed
+from the soju configuration, all client configurations also need to be updated
+accordingly. This can be cumbersome especially when dealing with many clients.
+
+To address this issue, soju supports a _multi-upstream mode_. Instead of
+configuring multiple servers in the client, only one connection to the bouncer
+is required. soju will expose all channels and users from all configured
+networks on this single connection. Channel names and nicknames will be suffixed
+with the network name. For instance, the `#soju` channel will appear with the
+name `#soju/libera`, and to talk to `emersion` on OFTC one would need to send a
+message to `emersion/oftc`. The special `BouncerServ` service won't have a
+suffix.
+
+To enable this mode, connect to the bouncer with the username
+`<soju username>/*`.
+
+To add a new network, send messages to `BouncerServ`, for instance:
+
+    /msg BouncerServ network create -addr irc.libera.chat -name libera
+
+To join a channel or message a user, remember to use the correct suffix, for
+instance:
+
+    /join #soju/libera
+    /query emersion/libera