Index: doc/core/howto/tap.xhtml
===================================================================
--- doc/core/howto/tap.xhtml	(revision 23742)
+++ doc/core/howto/tap.xhtml	(working copy)
@@ -73,11 +73,11 @@
 <h2>Using the run plugin</h2>
 
 <p>
-   The most simple way to run your service is using the <code class="shell">twistd
-   run</code> plugin. It allows your application to put the service wherever
-   you want, and it doesn't have to be a plugin. Thus, the interface to provide
-   is simple: it just needs an <code>options</code> attribute and a
-   <code>makeService</code>method.  Let's imagine a directory structure:
+   The simplest way to run your service is using the <code class="shell">twistd
+   run</code> command.  It allows you to use <code class="shell">twistd</code> to
+   start a service with a minimum of coding overhead.  The interface to provide
+   to use this is simple: just provide <code>options</code> and <code>makeService
+   </code>.  Imagine the following directory structure:
 </p>
 
 <ul>
@@ -92,7 +92,7 @@
 </ul>
 
 <p>
-    Fill <strong>service.py</strong> with the following code:
+    And imagine <strong>service.py</strong> contains the following code:
 </p>
 
 <pre class="python">
@@ -105,15 +105,16 @@
 from myproject import MyFactory
 
 
-class Options(usage.Options):
+class MyServiceOptions(usage.Options):
     optParameters = [["port", "p", 1235, "The port number to listen on."]]
     longdesc = "Run this! It'll make your dog happy."
 
 
 class MyServiceMaker(object):
     implements(ISimpleServiceMaker)
-    options = Options
 
+    options = MyServiceOptions
+
     def makeService(self, options):
         """
         Construct a TCPServer from a factory defined in myproject.
@@ -125,23 +126,29 @@
 </pre>
 
 <p>
-    The <code>Options</code> class defines the options your service needs.  The
-    <code>longdesc</code> attribute will be printed when you'll call <code
-    class="shell">--help</code> on you service. The <code>MyServiceMaker</code>
-    implements the <code>ISimpleServiceMaker</code> interface, which needs an
-    <code>options</code> attribute and a <code>makeService</code> method. This
-    method is called with an <code>options</code> argument, instance of the
-    <code>option</code> attribute filled with the data passed at command line.
-    It returns a service you want to run, here a
-    <code>internet.TCPServer</code>. Note that you need to create an instance
-    of <code>MyServiceMaker</code>: <code class="shell">twistd shell</code>
-    takes an object that <strong>provides</strong>
-    <code>ISimpleServiceMaker</code>, not just implements it.
+    <code class="python">MyServiceMaker</code> implements <code class="API"
+    base="twisted.application.service">ISimpleServiceMaker</code>, providing
+    two important attributes.  First, <code class="python">options</code> is a
+    callable which returns a new option parsing object.  This object will
+    have <code class="python">parseOptions</code> called on it with a list of
+    arguments from the command line.  Afterwards, the object will be passed as
+    the only argument to <code class="python">MyServiceMaker.makeService
+    </code>.  <code class="python">makeService</code> is to return the <code
+    class="API" base="twisted.application.service">IService</code>
+    implementation which will be run by <code class="shell">twistd</code>,
+    in this case an <code class="API" base="twisted.application">
+    internet.TCPServer</code>.  Note that you need to create an instance of
+    <code class="python">MyServiceMaker</code> because <code class="shell">
+    twistd run</code> accepts the name of an object that <strong>provides
+    </strong> <code class="API" base="twisted.application.service">
+    ISimpleServiceMaker</code>, not the name of an object that <strong>
+    implements</strong> it.
 </p>
 
 <p>
     To run this service, you call the run plugin with twistd, passing the fully
-    qualified named of your object providing <code>ISimpleServiceMaker</code>.
+    qualified named of your object providing <code class="API" base="twisted.application.service">
+    ISimpleServiceMaker</code>.
 </p>
 
 <pre class="shell">
@@ -149,19 +156,22 @@
 </pre>
 
 <p>
-    If you want to be even straightforward, it's important to know that a
-    module can provide the <code class="python">ISimpleServiceMaker</code>
-    interface. So if you put the following code instead in service.py:
+    It's also possible for a module to provide <code class="API"
+    base="twisted.application.service">ISimpleServiceMaker</code>.  This
+    is useful if the implementation is stateless or multiple instances
+    are not required.  For example, the above service.py could be rewritten
+    like this:
 </p>
 
 <pre class="python">
+from zope.interface import moduleProvides
+
 from twisted.python import usage
-from twisted.application import internet
-
+from twisted.application import service, internet
 from myproject import MyFactory
 
 
-class Options(usage.Options):
+class options(usage.Options):
     optParameters = [["port", "p", 1235, "The port number to listen on."]]
     longdesc = "Run this! It'll make your dog happy."
 
@@ -171,6 +181,8 @@
     Construct a TCPServer from a factory defined in myproject.
     """
     return internet.TCPServer(int(options["port"]), MyFactory())
+
+moduleProvides(service.ISimpleServiceMaker)
 </pre>
 
 <p>
@@ -186,12 +198,14 @@
 <p>
     The other way to run a server is by creating a <code
     class="shell">twistd</code> plugin. The main advantage of this method
-    towards the <code>run</code> plugin is automatic discovery: whereas you
+    over the <code>run</code> plugin is automatic discovery: whereas you
     have to know the full name of your service to use the <code>run</code>
-    plugin, <code class="shell">twistd</code> will list you every plugin it can
-    found. It also supports a description that will be printed when you call
-    <code class="shell">twistd --help</code> .The following directory structure
-    is assumed of your project:</p>
+    plugin, <code class="shell">twistd</code> can present a list of every
+    plugin available.  Plugins also add support for descriptions which will
+    be included in the list presented by <code class="shell">twistd --help
+    </code> .The following directory structure is assumed of your project:
+</p>
+
 <ul>
   <li><strong>MyProject</strong> - Top level directory
     <ul>