Update chat.sr.ht quickstart docs

1 files changed, 66 insertions, 23 deletions

diff --git a/chat.sr.ht/quickstart.md b/chat.sr.ht/quickstart.md
index 388ce7c..deb4fee 100644
--- a/chat.sr.ht/quickstart.md
+++ b/chat.sr.ht/quickstart.md
@@ -1,33 +1,76 @@
 # chat.sr.ht quick-start for experienced IRC users
 
-The webchat is available at [chat.sr.ht](https://chat.sr.ht) and requires no
-configuration to use. It will automatically connect you to your bouncer account.
-You can also connect directly to the bouncer using your own IRC client.
+chat.sr.ht provides an IRC bouncer, which maintains a persistent IRC session for
+you with one or more "upstream" IRC networks. For example, you may connect to
+chat.sr.ht, then chat.sr.ht will connect to [Libera Chat][libera] for you, and
+it will maintain a persistent connection while you're away. Setting up
+chat.sr.ht is thus two steps: connecting to chat.sr.ht, and configuring which
+upstream networks you want chat.sr.ht to connect to.
 
-<!-- Note: update chat.sr.ht/bouncer-usage.md if changing this -->
+[libera]: https://libera.chat
 
-To connect with a third-party IRC client, you will need to generate an OAuth 2.0
-personal access token to use as your server password. Visit [the personal access
-token issuance page](https://meta.sr.ht/oauth2/personal-token?grants=meta.sr.ht/PROFILE:RO)
-and generate a token.
+The webchat is available at [https://chat.sr.ht](https://chat.sr.ht) and
+requires no configuration to use. It will automatically connect you to your
+bouncer account. Instructions for configuring your upstream networks are then
+shown on-screen.
+
+## Connecting with your own IRC client
+
+You can also connect directly to the bouncer using your own IRC client. The
+easiest way to use the bouncer is to use a [plugin for your client][config]
+which implements the "soju.im/bouncer-networks" extension. This allows you to
+set up your bouncer connection details just once, then automatically configure
+all of your upstream IRC networks. If your client does not have a supported
+plugin, or you would prefer to configure networks manually, see the next
+section.
+
+[config]: https://git.sr.ht/~emersion/soju/tree/master/item/contrib/clients.md
+
+To set up your bouncer connection, you will need to generate an OAuth 2.0
+personal access token to use as the server password. Visit [the personal access
+token issuance page][token] to generate a token. Then add a newtork to your IRC
+client using the following credentials:
+
+[token]: https://meta.sr.ht/oauth2/personal-token?grants=meta.sr.ht/PROFILE:RO
 
 <dl>
-<dt>Hostname</dt><dd>chat.sr.ht</dd>
-<dt>Port</dt><dd>6697</dd>
-<dt>SSL/TLS</dt><dd>Yes</dd>
-<dt>SASL</dt><dd>Yes</dd>
-<dt>Username</dt><dd><em>your sourcehut username</em></dd>
-<dt>Password</dt><dd><em>your personal access token</em></dd>
+  <dt>Hostname</dt><dd>chat.sr.ht</dd>
+  <dt>Port</dt><dd>6697</dd>
+  <dt>SSL/TLS</dt><dd>Yes</dd>
+  <dt>SASL</dt><dd>Yes</dd>
+  <dt>Username</dt><dd><em>your sourcehut username</em></dd>
+  <dt>Password</dt><dd><em>your personal access token</em></dd>
 </dl>
 
-If you intend to use multiple clients, it is recommended that you append
-"@*clientname*" to your username, using an arbitrary unique string to identify
-each client. If your IRC client does not support soju's
-"soju.im/bouncer-networks" extension (check if [a plugin is available][config]),
-you may want to configure separate connections for each network by using the
-username format `username/network-name@client-name`.
+This will connect you to the bouncer, but you will still have to configure any
+upstream networks you wish to use by chatting with the special "BouncerServ"
+user. Use `/msg BouncerServ help` for a full list of supported commands.
 
-See [client-specific configuration][config] for recommended configuration steps
-specific to your preferred IRC client.
+To add a new IRC network via BouncerServ:
 
-[config]: https://git.sr.ht/~emersion/soju/tree/master/item/contrib/clients.md
+```
+/msg BouncerServ network create -addr <hostname> [options...]
+```
+
+See [soju(1)] for details on the supported options.
+
+[soju(1)]: https://soju.im/doc/soju.1.html#IRC_SERVICE
+
+## Connecting without a client plugin
+
+Connecting without a plugin is also possible. Using the same configuration
+settings recommended above, connect at least once and configure your upstream
+networks with BouncerServ (or set them up with the webchat). Then, configure a
+new IRC network in your IRC client for each upstream network you want to connect
+to using the same settings, but update your username to the format
+"*username*/*network-name*". For instance, I use "sircmpwn/liberachat" to
+connect to my Libera upstream.
+
+## Multi-client identification
+
+If you intend to use multiple clients, it is recommended that you append
+"@*clientname*" to your username. For example, I might use
+"sircmpwn@workstation" as my username for my desktop PC, and "sircmpwn@phone"
+for my smartphone. If you are configuring networks manually instead of using a
+plugin, the client ID is placed after the network name:
+"sircmpwn/liberachat@workstation".