Update chat.sr.ht quickstart docs

3 files changed, 80 insertions, 59 deletions

diff --git a/chat.sr.ht/bouncer-usage.md b/chat.sr.ht/bouncer-usage.md
index fadc4c2..e0e42e0 100644
--- a/chat.sr.ht/bouncer-usage.md
+++ b/chat.sr.ht/bouncer-usage.md
@@ -1,45 +1,22 @@
 # Using the chat.sr.ht bouncer
 
-For full details, refer to the [soju(1)](https://soju.im/doc/soju.1.html) man
-page. Information about common use-cases is provided here.
+For full details, refer to the [soju(1)] man page. Information about common
+use-cases is provided here.
 
 ## Connecting with a third-party IRC client
 
-<!-- Note: update chat.sr.ht/quickstart.md if changing this -->
+Check out the [quickstart for experienced IRC users][quickstart] for details on
+configuring your own IRC client for use with chat.sr.ht.
 
-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.
-
-<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>
-</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`.
-
-See [client-specific configuration][config] for recommended configuration steps
-specific to your preferred IRC client.
-
-[config]: https://git.sr.ht/~emersion/soju/tree/master/item/contrib/clients.md
+[quickstart]: /chat.sr.ht/quickstart.md
 
 ## Managing your IRC networks
 
-The webchat at [chat.sr.ht](https://chat.sr.ht) provides a UI for managing your
-bouncer networks. Third-party clients with soju support may detect the bouncer
-and offer similar functionality. If not, you can also message BouncerServ to
-configure soju. Use `/msg BouncerServ help` for a full list of supported
-commands.
+The webchat at [https://chat.sr.ht](https://chat.sr.ht) provides a UI for
+managing your bouncer networks. Third-party clients with soju support may detect
+the bouncer and offer similar functionality. If not, you can also message
+BouncerServ to configure soju. Use `/msg BouncerServ help` for a full list of
+supported commands.
 
 To add a new IRC network via BouncerServ:
 
@@ -47,8 +24,9 @@ To add a new IRC network via BouncerServ:
 /msg BouncerServ network create -addr <hostname> [options...]
 ```
 
-See [soju(1)](https://soju.im/doc/soju.1.html#IRC_SERVICE) for details on the
-supported options.
+See [soju(1)] for details on the supported options.
+
+[soju(1)]: https://soju.im/doc/soju.1.html#IRC_SERVICE
 
 ## Detaching from channels
 
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".
diff --git a/index.html b/index.html
index ff33cd1..25a58d9 100644
--- a/index.html
+++ b/index.html
@@ -136,7 +136,7 @@ dt {
   </div>
   <div class="col-md-4">
     <dt>
-      <strong>chat.sr.ht</strong>: IRC chat support
+      <strong>chat.sr.ht</strong>: IRC chat rooms
     </dt>
     <dd>
       <a href="/chat.sr.ht">User Manual</a>