Documentation tweaks

- Add advanced-service-config to TOC
- Move "matching SERVICE name" note to docs/t/services-api.md
- Various wording / grammar tweaks

docs/README.md

@@ -11,6 +11,7 @@ This folder contains general documentation for PyLink IRC services.
 
 - [Automode & Exttargets Guide](automode.md)
 - [Advanced Relay Configuration](advanced-relay-config.md)
+- [Advanced Services Configuration](advanced-services-config.md)
 - [PyLink Permissions Reference](permissions-reference.md)
 
 ----

docs/advanced-services-config.md

@@ -1,15 +1,10 @@
-# Advanced Service Config
+# Advanced Services Configuration
 
 There are some service configuration options that you may want to be aware of.
 
-**NOTE**: Your SERVICE name in the `utils.registerService("SERVICE", desc=desc)`
-call and the service configuration in 'SERVICE::' **MUST** match for these
-directives to apply.
-
-
 #### Nick / Ident
 
-In addition to setting a per-server 'nick' or 'ident' using,
+You can override the `nick` or `ident` of a service bot using a directive liek this:
 
 ```yaml
 servers:
@@ -17,9 +12,9 @@ servers:
         # ...
         SERVICE_nick: OTHERNICK
         SERVICE_ident: OTHERIDENT
-``` 
+```
 
-You can also just set an arbitrary nick/ident using a per-**service** directive.
+You can also set an arbitrary nick/ident using a per-**service** directive.
 
 ```yaml
 SERVICE:
@@ -27,20 +22,19 @@ SERVICE:
     ident: OTHERIDENT
 ```
 
-#### JoinModes
+#### joinmodes
 
-When joining a channel, ServiceBot Instances will just join and sit there.
-However, you can set a mode that the bot will ask for when it joins any channel.
+By default, service bots join channels without giving themselves any modes. You can configure what modes a service bot joins channels with using this directive:
 
 ```yaml
 SERVICE:
     joinmodes: 'o'
 ```
 
-This would request the mode 'o' (usually op on most IRCds) when joining the channel.
+This would request the mode 'o' (op on most IRCds) when joining the channel.
 
 Technically any mode can be put here, but if an IRCd in question doesn't support
-the mode then it just ignores it.
+the mode then it will be ignored.
 
 You can also use combinations of modes, such as 'ao' (usually admin/protect + op)
 
@@ -51,17 +45,17 @@ SERVICE:
 
 Combinations should work provided an IRCd in question supports it.
 
-#### Prefix
+#### Fantasy prefix
 
-You can also set the Service Bots fantasy prefix, of course this is only
-applicable if the 'fantasy' plugin is loaded.
+You can also set the service bot's fantasy prefix; of course this is only
+applicable if the `fantasy` plugin is loaded.
 
 The setting allows for one or more characters to be set as the prefix.
 
 ```yaml
 SERVICE:
-    prefix: './' 
+    prefix: './'
 ```
 
-This is perfectly valid, as is any other string.
+The above is perfectly valid, as is any other string.
 

docs/technical/services-api.md

@@ -2,7 +2,7 @@
 
 Starting with PyLink 0.9.x, a services bot API was introduced to make writing custom services slightly easier. PyLink's Services API automatically connects service bots, and handles rejoin on kick/kill all by itself, meaning less code is needed per plugin to have functional service bots.
 
-## Creating new services
+## Creating new service bots
 
 Services can be created (registered) using code similar to the following in a plugin:
 
@@ -28,6 +28,8 @@ myservice = utils.registerService("myservice", desc=desc)
 - `manipulatable` - Determines whether the bot is marked manipulatable. Only manipulatable clients can be force joined, etc. using PyLink commands. Defaults to False.
 - `desc` - Sets the command description of the service. This is shown in the default HELP command if enabled.
 
+**NOTE**: It is a good practice for the SERVICE name in `utils.registerService("SERVICE")` to match your plugin name, as the service bot API implicitly loads [configuration options](../advanced-services-config.md) from config blocks named `SERVICE:`.
+
 ### Getting the UID of a bot
 
 Should you want to get the UID of a service bot on a specific server, use `myservice.uids.get('irc.name')`