Update IRC channel docs

- improve the wording about ChanServ usage
- add some more examples
- fix some general formatting stuff

Change-Id: I96651956264ea8626d0b2bdab89ea5dbea33f4ad

doc/source/irc.rst

@@ -14,7 +14,6 @@ At a Glance
 ===========
 
 :Hosts:
-  * https://eavesdrop01.opendev.org/irclogs/
   * https://meetings.opendev.org/
   * https://ptg.opendev.org/
   * https://wiki.openstack.org/wiki/Infrastructure_Status
@@ -54,13 +53,13 @@ Join #opendev and ask for help if you have any trouble with any of these
 commands.
 
 NOTE: Channel admin should issue the access commands above BEFORE adding
-channel to gerritbot and accessbot, otherwise Zuul will fail tests.
+the channel to gerritbot and accessbot, otherwise Zuul will fail tests.
 
 Service overview
 ================
 
 The OpenDev team runs Limnoria `Limnoria
-<https://github.com/ProgVal/Limnoria>`__ on `eavesdrop01.opendev.org`
+<https://github.com/ProgVal/Limnoria>`__ on ``eavesdrop01.opendev.org``
 to provide channel and meeting logs.
 
 Channel logs are provided by Limnoria's inbuilt channel logger.
@@ -142,11 +141,14 @@ https://meetings.opendev.org/meetings/
 
 The bot also has the ability to sit in a channel for the sole purpose
 of logging channel activity, not just meetings. Standard channel logs
-are sent to http://meetings.opendev.org/irclogs/
+are sent to https://meetings.opendev.org/irclogs/
 
 The configuration for specific channel logging can be found in ,
 :git_file:`inventory/service/group_vars/eavesdrop.yaml`.
 
+It is suggested to inform users that the channel is getting logged,
+usually this is being done by mentioning it in the channel topic.
+
 .. _statusbot:
 
 Statusbot
@@ -214,8 +216,8 @@ Accessbot
 =========
 
 Accessbot defines access that should apply to all channels. Teams can add new
-channels to accessbot/channels.yaml and optionally set additional channel
-admins or ops, or specific mode overrides.
+channels to :config:`accessbot/channels.yaml` and optionally set additional
+channel admins or ops, or specific mode overrides.
 
 For typical day-to-day actions like updating channel topics or banning
 disruptive users, volunteer ops are sufficient. If the team wishes to retain
@@ -260,22 +262,33 @@ This is not a comprehensive overview of commands available to individuals
 running IRC channels on OFTC, but a basic overview of some of the common
 commands which may be required for channel operators.
 
-Operator status is sometimes required to perform certain commands in your
-channel (though most everything can be done through `/msg chanserv` commands
-instead if permission flags are set correctly). To give yourself operator
-status in a channel, use the following command::
+If you are curious as to who has access to a channel, you can issue this
+command, even if you are not an operator::
 
-  /msg chanserv op #channel
+  /msg chanserv access #channel list
 
-You don't need to become an operator to change the topic, this can be done
-via Chanserv::
+All of the remaining commands in this section are only available to persons
+that are listed in the above mentioned access list, feel free to ask one of
+them for help if you need something done, like a channel topic being updated.
+
+Most actions can be done directly via Chanserv, like setting the channel topic::
 
   /msg chanserv set #channel topic New topic goes here.
 
-If you are curious as to who has access to a channel, you can issue this
-command::
+In order to see an overview of the available commands, use::
 
-  /msg chanserv access #channel list
+  /msg chanserv help
+
+Operator status is sometimes required to perform certain commands in your
+channel, for example when sending admin commands to the PTG bot.
+To give yourself operator status in a channel, use the following command::
+
+  /msg chanserv op #channel
+
+It is advised however to not stay op-ed for longer than required, so when
+you are finished with your task, you can remove your status again with::
+
+  /msg chanserv deop #channel
 
 Banning Disruptive Users
 ========================
@@ -288,7 +301,7 @@ channel is to add them to Chanserv's auto-kick list like so::
 This will immediately and anonymously kick them from the channel, and prevent
 them from rejoining until explicitly removed from the akick list again.
 
-Banning of disruptive users is also available with the `/ban` command, see your
+Banning of disruptive users is also available with the ``/ban`` command, see your
 client documentation for syntax, though this will require opping yourself in
 the channel first.
 
@@ -334,7 +347,7 @@ Tips
 
 * Collect the list of users and send a message in channel to each of them
   explaining that the channel has moved.
-* Some folks simply won't leave and join the new channel, you can /kick
+* Some folks simply won't leave and join the new channel, you can ``/kick``
   them after a bit of time (a day? a week?) to get their client to join
   the new channel.
 * Don't leave the channel until everything is done, it's non-trivial to
@@ -345,14 +358,18 @@ Troubleshooting
 
 Bots may stop responding, common steps to troubleshoot the problem are:
 
-1. Check status of the bot, with::
+1. Check status of the bot containers, with::
 
-     service xxxbot status
+     sudo docker ps -a
 
    If the bot is stopped, start it again. Restart the bot if you see
    it's running but not operating properly.
 
-2. On bot restart, it may show problems connecting to irc.oftc.net.
+2. For some bots you can look at their logs with a command like::
+
+     sudo docker logs gerritbot-docker_gerritbot_1 2>&1 | less
+
+3. On bot restart, it may show problems connecting to irc.oftc.net.
    If bot logs show it's stopped on connection, you can manually try
    with::