Update command documentation based on feedback from docs team.

ticket #158

18 files changed, 323 insertions, 248 deletions

diff --git a/ipalib/plugins/aci.py b/ipalib/plugins/aci.py
index b6b40e260..ae1c40058 100644
--- a/ipalib/plugins/aci.py
+++ b/ipalib/plugins/aci.py
@@ -20,41 +20,67 @@
 """
 Directory Server Access Control Instructions (ACIs)
 
-ACI's are used to allow or deny access to information. This module is
-currently designed to allow, not deny, access, primarily write access.
+ACIs are used to allow or deny access to information. This module is
+currently designed to allow, not deny, access.
 
-The primary use of this plugin is to create low-level permission sets
-to allow a group to write or update entries or a set of attributes. This
-may include adding or removing entries as well. These groups are called
-taskgroups. These low-level permissions can be combined into roles
-that grant broader access. These roles are another type of group, rolegroups.
+The aci commands are designed to grant permissions that allow updating
+existing entries or adding or deleting new ones. The goal of the ACIs
+that ship with IPA is to provide a set of low-level permissions that
+grant access to special groups called taskgroups. These low-level
+permissions can be combined into roles that grant broader access. These
+roles are another type of group, rolegroups.
 
 For example, if you have taskgroups that allow adding and modifying users you
 could create a rolegroup, useradmin. You would assign users to the useradmin
 rolegroup to allow them to do the operations defined by the taskgroups.
 
-You can create ACIs that delegate permission so users in
-group A can write attributes on group B.
+You can create ACIs that delegate permission so users in group A can write
+attributes on group B.
 
 The type option is a map that applies to all entries in the users, groups or
 host location. It is primarily designed to be used when granting add
 permissions (to write new entries).
 
+An ACI consists of three parts:
+1. target
+2. permissions
+3. bind rules
+
+The target is a set of rules that define which LDAP objects are being
+targetted. This can include a list of attributes, an area of that LDAP
+tree or an LDAP filter.
+
+The permissions define what the ACI is allowed to do, they are one or more
+of:
+1. write - write one or more attributes
+2. read - read one or more attributes
+3. add - add a new entry to the tree
+4. delete - delete an existing entry
+5. all - all permissions are granted
+
+Note the distinction between attributes and entries. The permissions are
+independent, so being able to add a user does not mean that the user will
+be editabe.
+
+The bind rule defines who this ACI grants permissions to. The LDAP server
+allows this to be any valid LDAP entry but we encourage the use of
+taskgroups so that the rights can be easily shared through rolegroups.
+
 For a more thorough description of access controls see
 http://www.redhat.com/docs/manuals/dir-server/ag/8.0/Managing_Access_Control.html
 
 EXAMPLES:
 
- Add an ACI so the group 'secretaries' can update the address on any user:
+ Add an ACI so that the group "secretaries" can update the address on any user:
    ipa aci-add --attrs=streetAddress --memberof=ipausers --group=secretaries --permissions=write "Secretaries write addresses"
 
  Show the new ACI:
    ipa aci-show "Secretaries write addresses"
 
- Add an ACI that allows members of the 'addusers' taskgroup to add new users:
+ Add an ACI that allows members of the "addusers" taskgroup to add new users:
    ipa aci-add --type=user --taskgroup=addusers --permissions=add "Add new users"
 
-The show command will show the raw DS ACI.
+The show command shows the raw 389-ds ACI.
 
 IMPORTANT: When modifying the target attributes of an existing ACI you
 must include all existing attributes as well. When doing an aci-mod the
@@ -77,7 +103,7 @@ _type_map = {
 }
 
 _valid_permissions_values = [
-    u'read', u'write', u'add', u'delete', u'selfwrite', u'all'
+    u'read', u'write', u'add', u'delete', u'all'
 ]
 
 class ListOfACI(output.Output):
@@ -279,7 +305,7 @@ class aci(Object):
             cli_name='permissions',
             label=_('Permissions'),
             doc=_('comma-separated list of permissions to grant' \
-                '(read, write, add, delete, selfwrite, all)'),
+                '(read, write, add, delete, all)'),
             normalizer=_normalize_permissions,
         ),
         List('attrs?',
diff --git a/ipalib/plugins/cert.py b/ipalib/plugins/cert.py
index 8920cfe4f..1154e2e30 100644
--- a/ipalib/plugins/cert.py
+++ b/ipalib/plugins/cert.py
@@ -24,7 +24,7 @@ IPA certificate operations
 
 Implements a set of commands for managing server SSL certificates.
 
-Certificate request come in the form of a Certificate Signing Request (CSR)
+Certificate request exist in the form of a Certificate Signing Request (CSR)
 in PEM format.
 
 If using the selfsign backend then the subject in the CSR needs to match
@@ -32,15 +32,16 @@ the subject configured in the server. The dogtag CA uses just the CN
 value of the CSR and forces the rest of the subject.
 
 A certificate is stored with a service principal and a service principal
-needs a host. So in order to request a certificate the following conditions
-must be met:
+needs a host.
 
-* The host exists
-* The service exists (or you use the --add option to automatically add it)
+In order to request a certificate:
+
+* The host must exist
+* The service must exist (or you use the --add option to automatically add it)
 
 EXAMPLES:
 
- Request a new certificate, add the principal:
+ Request a new certificate and add the principal:
    ipa cert-request --add --principal=HTTP/lion.example.com example.csr
 
  Retrieve an existing certificate:
@@ -55,7 +56,9 @@ EXAMPLES:
  Check the status of a signing request:
    ipa cert-status 10
 
-IPA currently immediately issues (or declines) all certificate requests.
+IPA currently immediately issues (or declines) all certificate requests so
+the status of a request is not normally useful. This is for future-use
+or the case where a CA does not immediately issue a certificate.
 """
 
 from ipalib import api, SkipPluginModule
diff --git a/ipalib/plugins/config.py b/ipalib/plugins/config.py
index b704a7a26..8b6095f74 100644
--- a/ipalib/plugins/config.py
+++ b/ipalib/plugins/config.py
@@ -18,14 +18,14 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
-Manage IPA configuration
+Manage the IPA configuration
 
-Manage default values tha IPA uses and some tuning parameters:
+Manage the default values tha IPA uses and some of its tuning parameters.
 
- Show the current configuration:
+ To show the current configuration:
    ipa config-show
 
- Modify the configuration:
+ To modify the configuration:
    ipa config-mod --maxusername=99
 
 The available options are:
@@ -48,7 +48,7 @@ how many records may be returned on a given search.
 Server Configuration.
 
   --enable-migration=BOOL Enable migration mode
-  --subject=STR           base for certificate subjects (OU=Test,O=Example)
+  --subject=STR           Base for certificate subjects (OU=Test,O=Example)
 
 """
 
@@ -126,7 +126,7 @@ class config(LDAPObject):
         Str('ipacertificatesubjectbase?',
             cli_name='subject',
             label=_('Certificate Subject base'),
-            doc=_('base for certificate subjects (OU=Test,O=Example)'),
+            doc=_('Base for certificate subjects (OU=Test,O=Example)'),
         ),
     )
 
@@ -153,7 +153,7 @@ api.register(config_mod)
 
 class config_show(LDAPRetrieve):
     """
-    Display configuration options.
+    Show the current configuration.
     """
 
 api.register(config_show)
diff --git a/ipalib/plugins/dns.py b/ipalib/plugins/dns.py
index d651ec041..b154b5dff 100644
--- a/ipalib/plugins/dns.py
+++ b/ipalib/plugins/dns.py
@@ -17,10 +17,10 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
-Domain Name System (DNS) plugin
+Domain Name System (DNS) plug-in
 
 Implements a set of commands useful for manipulating DNS records used by
-the BIND LDAP plugin.
+the BIND LDAP plug-in.
 
 EXAMPLES:
 
@@ -42,10 +42,10 @@ EXAMPLES:
  Show zone example.com:
    ipa dns-show example.com
 
- Find zone with 'example' in it's domain name:
+ Find zone with "example" in it's domain name:
    ipa dns-find example
 
- Find records for resources with 'www' in their name in zone example.com:
+ Find records for resources with "www" in their name in zone example.com:
    ipa dns-find-rr example.com www
 
  Find A records for resource www in zone example.com
diff --git a/ipalib/plugins/group.py b/ipalib/plugins/group.py
index 9bf5b1de8..616eff2a7 100644
--- a/ipalib/plugins/group.py
+++ b/ipalib/plugins/group.py
@@ -20,43 +20,49 @@
 """
 Groups of users
 
-Manage groups of users. By default new groups are not Posix groups.
-You can mark it as Posix at creation time with the --posix flag and
-can promose a non-Posix group using the --posix flag in group-mod.
-Once a group is a Posix group there is no way to undo this.
+Manage groups of users. By default, new groups are not POSIX groups. You
+can add the --posix to the group-add command to mark a new group
+as POSIX, and you can use the same argument to the group-mod command to
+convert a non-POSIX group to a POSIX group. POSIX groups cannot be
+converted to non-POSIX groups.
 
 Every group must have a description.
 
-Posix groups must have a group id number (gid). Changing a gid is
-supported but can have impact on your file permissions.
+POSIX groups must have a Group ID number (GID). Changing a GID is
+supported but can have impact on your file permissions. It is not necessary
+to supply a GID when creating a group. IPA will generate one automatically
+if it is not provided.
 
 EXAMPLES:
 
  Add a new group:
    ipa group-add --desc='local administrators' localadmins
 
- Add a new posix group:
+ Add a new POSIX group:
    ipa group-add --posix --desc='remote administrators' remoteadmins
 
- Promote a non-posix group to posix:
+ Convert a non-POSIX group to posix:
    ipa group-mod --posix localadmins
 
- Create a group with a specific group ID number"
+ Add a new POSIX group with a specific Group ID number:
    ipa group-add --posix --gid=500 --desc='unix admins' unixadmins
 
+ Add a new POSIX group and let IPA assign a Group ID number:
+   ipa group-add --posix --desc='printer admins' printeradmins
+
  Remove a group:
    ipa group-del unixadmins
 
- Manage group membership, nested groups:
+ To add the "remoteadmins" group to the "localadmins" group:
    ipa group-add-member --groups=remoteadmins localadmins
 
- Manage group membership, users:
+ Add a list of users to the "localadmins" group:
    ipa group-add-member --users=test1,test2 localadmins
 
- Manage group membership, users:
+ Remove a user from the "localadmins" group:
    ipa group-remove-member --users=test2 localadmins
 
- Show a group:
+ Display information about a named group.
    ipa group-show localadmins
 """
 
@@ -122,7 +128,7 @@ api.register(group)
 
 class group_add(LDAPCreate):
     """
-    Create new group.
+    Create a new group.
     """
 
     msg_summary = _('Added group "%(value)s"')
@@ -176,7 +182,7 @@ api.register(group_del)
 
 class group_mod(LDAPUpdate):
     """
-    Modify group.
+    Modify a group.
     """
 
     msg_summary = _('Modified group "%(value)s"')
@@ -218,7 +224,7 @@ api.register(group_find)
 
 class group_show(LDAPRetrieve):
     """
-    Display group.
+    Display information about a named group.
     """
 
 api.register(group_show)
@@ -226,7 +232,7 @@ api.register(group_show)
 
 class group_add_member(LDAPAddMember):
     """
-    Add members to group.
+    Add members to a group.
     """
 
 api.register(group_add_member)
@@ -234,7 +240,7 @@ api.register(group_add_member)
 
 class group_remove_member(LDAPRemoveMember):
     """
-    Remove members from group.
+    Remove members from a group.
     """
 
 api.register(group_remove_member)
diff --git a/ipalib/plugins/hbac.py b/ipalib/plugins/hbac.py
index 0df012d49..4d7681c48 100644
--- a/ipalib/plugins/hbac.py
+++ b/ipalib/plugins/hbac.py
@@ -17,32 +17,40 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
-Host based access control
+Host-based access control
 
-Control who can access what services where from where. With HBAC
-you can control which users or groups of users may access a service
-or group of services, additionally restricting the source and source
-hosts.
+Control who can access what services on what hosts and from where. You
+can use HBAC to control which users or groups on a source host can
+access a service, or group of services, on a target host. You can also
+control the times that the rule is active.
 
-You can also control the times that the rule is active.
+You can also specify a category of users, target hosts, and source
+hosts. This is currently limited to "all", but might be expanded in the
+future.
 
-It is possible to specify a category of users, hosts or source hosts.
-Currently this is limited to 'all' but may be expanded in the future.
+The access time(s) of a host are cumulative and are not guaranteed to be
+applied in the order displayed.
 
-Hosts and source hosts must be host entries in IPA (see host plugin).
+Target hosts and source hosts in HBAC rules must be hosts managed by IPA.
+
+The available services and groups of services are controlled by the
+hbacsvc and hbacsvcgroup plug-ins respectively.
 
 EXAMPLES:
 
- Create a new rule that grants all users access to the host 'server' from
+ Create a rule, "test1", that grants all users access to the host "server" from
  anywhere:
    ipa hbac-add --type=allow --usercat=all --srchostcat=all test1
    ipa hbac-add-host --hosts=server.example.com test1
 
- Show an HBAC rule:
+ Display the properties of a named HBAC rule:
    ipa hbac-show test1
 
- Add an access time to a rule:
+ Specify that the rule "test1" be active every day between 0800 and 1400:
    ipa hbac-add-accesstime --time='periodic daily 0800-1400' test1
+
+  Specify that the rule "test1" be active once, from 10:32 until 10:33 on
+  December 16, 2010:
    ipa hbac-add-accesstime --time='absolute 201012161032 ~ 201012161033' test1
 
  Create a rule for a specific service. This lets the user john access
@@ -51,10 +59,10 @@ EXAMPLES:
    ipa hbac-add-user --users=john john_sshd
    ipa hbac-add-service --hbacsvcs=sshd john_sshd
 
- Disable a rule:
+ Disable a named HBAC rule:
    ipa hbac-disable test1
 
- Remove an HBAC rule:
+ Remove a named HBAC rule:
    ipa hbac-del allow_server
 """
 
@@ -186,7 +194,7 @@ api.register(hbac)
 
 class hbac_add(LDAPCreate):
     """
-    Create new HBAC rule.
+    Create a new HBAC rule.
     """
     def pre_callback(self, ldap, dn, entry_attrs, attrs_list, *keys, **options):
         if not dn.startswith('cn='):
@@ -203,7 +211,7 @@ api.register(hbac_add)
 
 class hbac_del(LDAPDelete):
     """
-    Delete HBAC rule.
+    Delete an HBAC rule.
     """
 
 api.register(hbac_del)
@@ -211,7 +219,7 @@ api.register(hbac_del)
 
 class hbac_mod(LDAPUpdate):
     """
-    Modify HBAC rule.
+    Modify an HBAC rule.
     """
 
 api.register(hbac_mod)
@@ -227,7 +235,7 @@ api.register(hbac_find)
 
 class hbac_show(LDAPRetrieve):
     """
-    Dispaly HBAC rule.
+    Display the properties of an HBAC rule.
     """
 
 api.register(hbac_show)
@@ -235,7 +243,7 @@ api.register(hbac_show)
 
 class hbac_enable(LDAPQuery):
     """
-    Enable HBAC rule.
+    Enable an HBAC rule.
     """
     def execute(self, cn):
         ldap = self.obj.backend
@@ -259,7 +267,7 @@ api.register(hbac_enable)
 
 class hbac_disable(LDAPQuery):
     """
-    Disable HBAC rule.
+    Disable an HBAC rule.
     """
     def execute(self, cn):
         ldap = self.obj.backend
@@ -283,7 +291,7 @@ api.register(hbac_disable)
 
 class hbac_add_accesstime(LDAPQuery):
     """
-    Add access time to HBAC rule.
+    Add an access time to an HBAC rule.
     """
 
     takes_options = (
@@ -360,7 +368,7 @@ api.register(hbac_remove_accesstime)
 
 class hbac_add_user(LDAPAddMember):
     """
-    Add users and groups affected by HBAC rule.
+    Add users and groups to an HBAC rule.
     """
     member_attributes = ['memberuser']
     member_count_out = ('%i object added.', '%i objects added.')
@@ -370,7 +378,7 @@ api.register(hbac_add_user)
 
 class hbac_remove_user(LDAPRemoveMember):
     """
-    Remove users and groups affected by HBAC rule.
+    Remove users and groups from an HBAC rule.
     """
     member_attributes = ['memberuser']
     member_count_out = ('%i object removed.', '%i objects removed.')
@@ -380,7 +388,7 @@ api.register(hbac_remove_user)
 
 class hbac_add_host(LDAPAddMember):
     """
-    Add hosts and hostgroups affected by HBAC rule.
+    Add target hosts and hostgroups to an HBAC rule
     """
     member_attributes = ['memberhost']
     member_count_out = ('%i object added.', '%i objects added.')
@@ -390,7 +398,7 @@ api.register(hbac_add_host)
 
 class hbac_remove_host(LDAPRemoveMember):
     """
-    Remove hosts and hostgroups affected by HBAC rule.
+    Remove target hosts and hostgroups from a HBAC rule.
     """
     member_attributes = ['memberhost']
     member_count_out = ('%i object removed.', '%i objects removed.')
@@ -400,7 +408,7 @@ api.register(hbac_remove_host)
 
 class hbac_add_sourcehost(LDAPAddMember):
     """
-    Add source hosts and hostgroups affected by HBAC rule.
+    Add source hosts and hostgroups from a HBAC rule.
     """
     member_attributes = ['sourcehost']
     member_count_out = ('%i object added.', '%i objects added.')
@@ -410,7 +418,7 @@ api.register(hbac_add_sourcehost)
 
 class hbac_remove_sourcehost(LDAPRemoveMember):
     """
-    Remove source hosts and hostgroups affected by HBAC rule.
+    Remove source hosts and hostgroups from an HBAC rule.
     """
     member_attributes = ['sourcehost']
     member_count_out = ('%i object removed.', '%i objects removed.')
@@ -420,7 +428,7 @@ api.register(hbac_remove_sourcehost)
 
 class hbac_add_service(LDAPAddMember):
     """
-    Add services affected by HBAC rule.
+    Add services to an HBAC rule.
     """
     member_attributes = ['memberservice']
     member_count_out = ('%i object added.', '%i objects added.')
@@ -430,7 +438,7 @@ api.register(hbac_add_service)
 
 class hbac_remove_service(LDAPRemoveMember):
     """
-    Remove source hosts and hostgroups affected by HBAC rule.
+    Remove source hosts and hostgroups from an HBAC rule.
     """
     member_attributes = ['memberservice']
     member_count_out = ('%i object removed.', '%i objects removed.')
diff --git a/ipalib/plugins/hbacsvc.py b/ipalib/plugins/hbacsvc.py
index 2383d70c0..d5302cdee 100644
--- a/ipalib/plugins/hbacsvc.py
+++ b/ipalib/plugins/hbacsvc.py
@@ -24,16 +24,17 @@ must match the service name that PAM is evaluating.
 
 EXAMPLES:
 
- Create a new service:
+ Add a new HBAC service:
    ipa hbacsvc-add tftp
 
- Update a service:
-   ipa hbacsvc-mod --desc='TFTP service' tftp
+ Modify an existing HBAC service:
+   ipa hbacsvc-mod --desc="TFTP service" tftp
 
- Find a service (this will find 2, the ftp service and the new tftp service):
+ Search for HBAC services. This example will return two results, the FTP
+ service and the newly-added tftp service:
    ipa hbacsvc-find ftp
 
- Remove a service:
+ Delete an HBAC service:
    ipa hbacsvc-del tftp
 
 """
@@ -78,7 +79,7 @@ api.register(hbacsvc)
 
 class hbacsvc_add(LDAPCreate):
     """
-    Add new HBAC service.
+    Add a new HBAC service.
     """
     msg_summary = _('Added service "%(value)s"')
 
@@ -96,7 +97,7 @@ api.register(hbacsvc_del)
 
 class hbacsvc_mod(LDAPUpdate):
     """
-    Modify HBAC service.
+    Modify an HBAC service.
     """
 
 api.register(hbacsvc_mod)
@@ -112,7 +113,7 @@ api.register(hbacsvc_find)
 
 class hbacsvc_show(LDAPRetrieve):
     """
-    Display HBAC service.
+    Display information about an HBAC service.
     """
 
 api.register(hbacsvc_show)
diff --git a/ipalib/plugins/hbacsvcgroup.py b/ipalib/plugins/hbacsvcgroup.py
index 53a8ca460..70dd32b13 100644
--- a/ipalib/plugins/hbacsvcgroup.py
+++ b/ipalib/plugins/hbacsvcgroup.py
@@ -19,25 +19,27 @@
 """
 HBAC Service Groups
 
-Manage groups of services for HBAC
+HBAC service groups can contain any number of individual services,
+or "members", and can also contain other service groups. Every group must
+have a description.
 
 EXAMPLES:
- 
- Create a group of HBAC services:
+
+ Add a new HBAC services group:
    ipa hbacsvcgroup-add --desc="login services" login
 
- Add some members to a HBAC service group:
+ Add members to an HBAC services group:
    ipa hbacsvcgroup-add-member --hbacsvcs=sshd,login login
 
- Show a group:
+ Display information about a named group:
    ipa hbacsvcgroup-show login
 
- A group can contain other groups, add a new group to login:
+ Add a new group to the "login" group:
    ipa hbacsvcgroup-add --desc="switch users" suers
    ipa hbacsvcgroup-add-member --hbacsvcs=su,su-l suers
    ipa hbacsvsgroup-add-member --hbacsvsgroups=suers login
 
- Remove a group:
+ Delete an HBAC services group:
    ipa hbacsvcgroup-del login
 """
 
@@ -94,7 +96,7 @@ api.register(hbacsvcgroup)
 
 class hbacsvcgroup_add(LDAPCreate):
     """
-    Create new hbacsvcgroup.
+    Add a new HBAC services group.
     """
     msg_summary = _('Added HBAC Service group "%(value)s"')
 
@@ -103,7 +105,7 @@ api.register(hbacsvcgroup_add)
 
 class hbacsvcgroup_del(LDAPDelete):
     """
-    Delete hbacsvcgroup.
+    Delete an HBAC services group.
     """
     msg_summary = _('Deleted HBAC Service group "%(value)s"')
 
@@ -112,7 +114,7 @@ api.register(hbacsvcgroup_del)
 
 class hbacsvcgroup_mod(LDAPUpdate):
     """
-    Modify hbacsvcgroup.
+    Modify an HBAC services group.
     """
     msg_summary = _('Modified HBAC Service group "%(value)s"')
 
@@ -121,7 +123,7 @@ api.register(hbacsvcgroup_mod)
 
 class hbacsvcgroup_find(LDAPSearch):
     """
-    Search the groups.
+    Search for an HBAC services group.
     """
     msg_summary = ngettext(
         '%(count)d group matched', '%(count)d groups matched', 0
@@ -132,7 +134,7 @@ api.register(hbacsvcgroup_find)
 
 class hbacsvcgroup_show(LDAPRetrieve):
     """
-    Display hbacsvcgroup.
+    Display information about an HBAC services group.
     """
 
 api.register(hbacsvcgroup_show)
@@ -140,7 +142,7 @@ api.register(hbacsvcgroup_show)
 
 class hbacsvcgroup_add_member(LDAPAddMember):
     """
-    Add members to hbacsvcgroup.
+    Add members to an HBAC services group.
     """
 
 api.register(hbacsvcgroup_add_member)
@@ -148,7 +150,7 @@ api.register(hbacsvcgroup_add_member)
 
 class hbacsvcgroup_remove_member(LDAPRemoveMember):
     """
-    Remove members from hbacsvcgroup.
+    Remove members from an HBAC services group.
     """
 
 api.register(hbacsvcgroup_remove_member)
diff --git a/ipalib/plugins/host.py b/ipalib/plugins/host.py
index 78d4d5a02..d207f5267 100644
--- a/ipalib/plugins/host.py
+++ b/ipalib/plugins/host.py
@@ -18,47 +18,49 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
-Hosts/Machines (Identity)
+Hosts/Machines
 
 A host represents a machine. It can be used in a number of contexts:
 - service entries are associated with a host
 - a host stores the host/ service principal
-- a host may be used in Host-Based Access Control (HBAC) rules
+- a host can be used in Host-Based Access Control (HBAC) rules
 - every enrolled client generates a host entry
 
 ENROLLMENT:
 
-There are three enrollment scenarios when enrolling a new client.
+There are three enrollment scenarios when enrolling a new client:
 
-1. You are enrolling as a full administrator (hostadmin rolegroup). The
-   host entry may exist or not.
-2. You are enrolling as a limited administrator (enrollhost rolegroup). The
-   host must already exist.
+1. You are enrolling as a full administrator. The host entry may exist
+   or not. A full administrator is a member of the hostadmin rolegroup
+   or the admins group.
+2. You are enrolling as a limited administrator. The host must already
+   exist. A limited administrator is a member of the enrollhost rolegroup.
 3. The host has been created with a one-time password.
 
-A host may only be enrolled once. If a client has enrolled and needs to
-be re-enrolled then the host entry needs to be removed and re-created.
-Note that this will result in all services for this host being removed too,
-and all SSL certificates associated with those services to be revoked.
+A host can only be enrolled once. If a client has enrolled and needs to
+be re-enrolled, the host entry must be removed and re-created. Note that
+re-creating the host entry will result in all services for the host being
+removed, and all SSL certificates associated with those services being
+revoked.
 
 A host can optionally store information such as where it is located,
 the OS that it runs, etc.
 
 EXAMPLES:
 
- Create a new host
-   ipa host-add --location='3rd floor lab' --locality=Dallas test.example.com
+ Add a new host:
+   ipa host-add --location="3rd floor lab" --locality=Dallas test.example.com
 
- Remove a host
+ Delete a host:
    ipa host-del test.example.com
 
- Create a new host with a one-time password
+ Add a new host with a one-time password:
    ipa host-add --os='Fedora 12' --password=Secret123 test.example.com
 
- Update information about a host
+ Modify information about a host:
    ipa host-mod --os='Fedora 12' test.example.com
 
- Disable the host kerberos key
+ Disable the host kerberos key:
    ipa host-disable test.example.com
 """
 
@@ -191,7 +193,7 @@ api.register(host)
 
 class host_add(LDAPCreate):
     """
-    Create new host.
+    Add a new host.
     """
 
     msg_summary = _('Added host "%(value)s"')
@@ -227,7 +229,7 @@ api.register(host_add)
 
 class host_del(LDAPDelete):
     """
-    Delete host.
+    Delete a host.
     """
 
     msg_summary = _('Deleted host "%(value)s"')
@@ -261,7 +263,7 @@ api.register(host_del)
 
 class host_mod(LDAPUpdate):
     """
-    Modify host.
+    Modify information about a host.
     """
 
     msg_summary = _('Modified host "%(value)s"')
@@ -328,7 +330,7 @@ api.register(host_find)
 
 class host_show(LDAPRetrieve):
     """
-    Display host.
+    Display information about a host.
     """
     has_output_params = (
         Flag('has_keytab',
@@ -351,7 +353,7 @@ api.register(host_show)
 
 class host_disable(LDAPQuery):
     """
-    Disable the kerberos key of this host.
+    Disable the kerberos key of a host.
     """
     has_output = output.standard_value
     msg_summary = _('Removed kerberos key from "%(value)s"')
diff --git a/ipalib/plugins/hostgroup.py b/ipalib/plugins/hostgroup.py
index ff97a1394..2f9cbab2c 100644
--- a/ipalib/plugins/hostgroup.py
+++ b/ipalib/plugins/hostgroup.py
@@ -20,24 +20,30 @@
 """
 Groups of hosts.
 
-This is useful for Host-Based Access Control (HBAC) to group a series
-of hosts together for applying access control.
+Manage groups of hosts. This is useful for applying access control to a
+number of hosts by using Host-based Access Control.
 
 EXAMPLES:
 
- Create a new host group:
-   ipa hostgroup-add --desc='Baltimore hosts' baltimore
+ Add a new host group:
+   ipa hostgroup-add --desc="Baltimore hosts" baltimore
 
- Add some hosts to the group:
+ Add another new host group:
+   ipa hostgroup-add --desc="Maryland hosts" maryland
+
+ Add members to the hostgroup:
    ipa hostgroup-add-member --hosts=box1,box2,box3 baltimore
 
- Remove a host from the group:
+ Add a hostgroup as a member of another hostgroup:
+   ipa hostgroup-add-member --hostgroups=baltimore maryland
+
+ Remove a host from the hostgroup:
    ipa hostgroup-remove-member --hosts=box2 baltimore
 
  Display a host group:
    ipa hostgroup-show baltimore
 
- Removey a host group:
+ Delete a hostgroup:
    ipa hostgroup-del baltimore
 """
 
@@ -94,7 +100,7 @@ api.register(hostgroup)
 
 class hostgroup_add(LDAPCreate):
     """
-    Create new hostgroup.
+    Add a new hostgroup.
     """
 
     msg_summary = _('Added hostgroup "%(value)s"')
@@ -104,7 +110,7 @@ api.register(hostgroup_add)
 
 class hostgroup_del(LDAPDelete):
     """
-    Delete hostgroup.
+    Delete a hostgroup.
     """
 
     msg_summary = _('Deleted hostgroup "%(value)s"')
@@ -114,7 +120,7 @@ api.register(hostgroup_del)
 
 class hostgroup_mod(LDAPUpdate):
     """
-    Modify hostgroup.
+    Modify a hostgroup.
     """
 
     msg_summary = _('Modified hostgroup "%(value)s"')
@@ -136,7 +142,7 @@ api.register(hostgroup_find)
 
 class hostgroup_show(LDAPRetrieve):
     """
-    Display hostgroup.
+    Display information about a hostgroup.
     """
 
 api.register(hostgroup_show)
@@ -144,7 +150,7 @@ api.register(hostgroup_show)
 
 class hostgroup_add_member(LDAPAddMember):
     """
-    Add members to hostgroup.
+    Add members to a hostgroup.
     """
 
 api.register(hostgroup_add_member)
@@ -152,7 +158,7 @@ api.register(hostgroup_add_member)
 
 class hostgroup_remove_member(LDAPRemoveMember):
     """
-    Remove members from hostgroup.
+    Remove members from a hostgroup.
     """
 
 api.register(hostgroup_remove_member)
diff --git a/ipalib/plugins/krbtpolicy.py b/ipalib/plugins/krbtpolicy.py
index 2c797fd13..5d773d205 100644
--- a/ipalib/plugins/krbtpolicy.py
+++ b/ipalib/plugins/krbtpolicy.py
@@ -19,13 +19,13 @@
 """
 Kerberos ticket policy
 
-There is a single kerberos ticket policy. This policy defines the
-maximum ticket lifetime (maximum life of a ticket) and maximum renewal
-age, the period during which the ticket is renewable.
+There is a single Kerberos ticket policy. This policy defines the
+maximum ticket lifetime and the maximum renewal age, the period during
+which the ticket is renewable.
 
 EXAMPLES:
 
- Display the current policy:
+ Display the current Kerberos ticket policy:
   ipa krbtpolicy-show
 
  Reset the policy to the default:
@@ -85,7 +85,7 @@ api.register(krbtpolicy)
 
 class krbtpolicy_mod(LDAPUpdate):
     """
-    Modify kerberos ticket policy.
+    Modify Kerberos ticket policy.
     """
     def pre_callback(self, ldap, dn, entry_attrs, attrs_list, *keys, **options):
         # disable all flag
@@ -99,7 +99,7 @@ api.register(krbtpolicy_mod)
 
 class krbtpolicy_show(LDAPRetrieve):
     """
-    Display kerberos ticket policy.
+    Display the current Kerberos ticket policy.
     """
     def pre_callback(self, ldap, dn, attrs_list, *keys, **options):
         # disable all flag
@@ -123,7 +123,7 @@ api.register(krbtpolicy_show)
 
 class krbtpolicy_reset(LDAPQuery):
     """
-    Reset kerberos ticket policy to default.
+    Reset Kerberos ticket policy to the default values.
     """
     has_output = output.standard_entry
 
diff --git a/ipalib/plugins/netgroup.py b/ipalib/plugins/netgroup.py
index d2ffc404e..144505be8 100644
--- a/ipalib/plugins/netgroup.py
+++ b/ipalib/plugins/netgroup.py
@@ -25,19 +25,19 @@ user and host values.
 
 EXAMPLES:
 
- Create a new netgroup:
-   ipa netgroup-add --desc='NFS admins' admins
+ Add a new netgroup:
+   ipa netgroup-add --desc="NFS admins" admins
 
- Add a member to the group:
+ Add members to the netgroup:
    ipa netgroup-add-member --users=tuser1,tuser2 admins
 
- Remove a member from the group:
+ Remove a member from the netgroup:
    ipa netgroup-remove-member --users=tuser2 admins
 
- Display a netgroup:
+ Display infromation about a netgroup:
    ipa netgroup-show admins
 
- Remove a netgroup:
+ Delete a netgroup:
    ipa netgroup-del admins
 """
 
@@ -131,7 +131,7 @@ api.register(netgroup)
 
 class netgroup_add(LDAPCreate):
     """
-    Create new netgroup.
+    Add a new netgroup.
     """
     has_output_params = output_params
     def pre_callback(self, ldap, dn, entry_attrs, attrs_list, *keys, **options):
@@ -149,7 +149,7 @@ api.register(netgroup_add)
 
 class netgroup_del(LDAPDelete):
     """
-    Delete netgroup.
+    Delete a netgroup.
     """
 
 api.register(netgroup_del)
@@ -157,7 +157,7 @@ api.register(netgroup_del)
 
 class netgroup_mod(LDAPUpdate):
     """
-    Modify netgroup.
+    Modify a netgroup.
     """
     has_output_params = output_params
 
@@ -166,7 +166,7 @@ api.register(netgroup_mod)
 
 class netgroup_find(LDAPSearch):
     """
-    Search the groups.
+    Search for a netgroup.
     """
     has_output_params = output_params
 
@@ -175,7 +175,7 @@ api.register(netgroup_find)
 
 class netgroup_show(LDAPRetrieve):
     """
-    Display netgroup.
+    Display information about a netgroup.
     """
     has_output_params = output_params
 
@@ -184,7 +184,7 @@ api.register(netgroup_show)
 
 class netgroup_add_member(LDAPAddMember):
     """
-    Add members to netgroup.
+    Add members to a netgroup.
     """
     has_output_params = LDAPAddMember.has_output_params + output_params
     member_attributes = ['memberuser', 'memberhost']
@@ -220,7 +220,7 @@ api.register(netgroup_add_member)
 
 class netgroup_remove_member(LDAPRemoveMember):
     """
-    Remove members from netgroup.
+    Remove members from a netgroup.
     """
     has_output_params = LDAPRemoveMember.has_output_params + output_params
     member_attributes = ['memberuser', 'memberhost']
diff --git a/ipalib/plugins/passwd.py b/ipalib/plugins/passwd.py
index f4f722f1e..ef515605e 100644
--- a/ipalib/plugins/passwd.py
+++ b/ipalib/plugins/passwd.py
@@ -17,23 +17,21 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
-User password changes
+Set a user's password
 
-Sets a user password. Normally a user can only change their own password.
-
-If someone other than user changes a password (e.g. helpdesk resets it)
+If someone other than user changes their password (e.g., Helpdesk resets it)
 then the password will need to be changed the first time it is used.
 This is so the end-user is the only one that knows the password.
 
-Password policy will control how often a password may be changed,
-what strength requirements there are and long the password history is.
+The IPA password policy controls how often a password may be changed,
+what strength requirements exist, and the length of the password history.
 
 EXAMPLES:
 
- Reset your own password:
+ To reset your own password:
    ipa passwd
 
- Change another user's password:
+ To change another user's password:
    ipa passwd tuser1
 """
 
@@ -45,7 +43,7 @@ from ipalib import _
 
 class passwd(Command):
     """
-    Change user password.
+    Set a user's password
     """
 
     takes_args = (
diff --git a/ipalib/plugins/pwpolicy.py b/ipalib/plugins/pwpolicy.py
index e7cfab654..dbbb47135 100644
--- a/ipalib/plugins/pwpolicy.py
+++ b/ipalib/plugins/pwpolicy.py
@@ -19,29 +19,31 @@
 """
 Password policy
 
-A password policy sets limitations on passwords including maximum lifetime,
-minimum lifetime, number of passwords to save in history, number of character
-classes required (for stronger passwords) and the password minimum length.
-
-By default there is a single global policy for all users. One can also
-create a password policy associate with a group. A user has only one
-password policy, either the group policy or the global policy. A group
-policy stands alone, it isn't a super-set of the global policy plus
+A password policy sets limitations on IPA passwords, including maximum
+lifetime, minimum lifetime, the number of passwords to save in
+history, the number of character classes required (for stronger passwords)
+and the minimum password length.
+
+By default there is a single, global policy for all users. You can also
+create a password policy to apply to a group. Each user is only subject
+to one password policy, either the group policy or the global policy. A
+group policy stands alone; it is not a super-set of the global policy plus
 custom settings.
 
 Each group password policy requires a unique priority setting. If a user
-is in multiple groups that have password policies this priority determines
-which password policy is applied. The lower the value the higher the priority.
+is in multiple groups that have password policies, this priority determines
+which password policy is applied. A lower value indicates a higher priority
+policy.
 
-A group password policy is automatically removed when the group it is
-assicated with it is removed.
+Group password policies are automatically removed when the groups they
+are associated with are removed.
 
 EXAMPLES:
 
- Update the global policy:
+ Modify the global policy:
    ipa pwpolicy-mod --minlength=10
 
- Create a group password policy:
+ Add a new group password policy:
    ipa pwpolicy-add --maxlife=90 --minlife=1 --history=10 --minclasses=3 --minlength=8 --priority=10 localadmins
 
  Display the global password policy:
@@ -49,11 +51,11 @@ EXAMPLES:
 
  Display a group password policy:
    ipa pwpolicy-show localadmins
- 
+
  Display the policy that would be applied to a given user:
    ipa pwpolicy-show --user=tuser1
 
- Modify a group policy:
+ Modify a group password policy:
    ipa pwpolicy-mod --minclasses=2 localadmins
 """
 
@@ -266,7 +268,7 @@ api.register(pwpolicy)
 
 class pwpolicy_add(LDAPCreate):
     """
-    Create new group password policy.
+    Add a new group password policy.
     """
     def get_args(self):
         yield self.obj.primary_key.clone(attribute=True, required=True)
@@ -295,7 +297,7 @@ api.register(pwpolicy_add)
 
 class pwpolicy_del(LDAPDelete):
     """
-    Delete group password policy.
+    Delete a group password policy.
     """
     def get_args(self):
         yield self.obj.primary_key.clone(attribute=True, required=True)
@@ -312,7 +314,7 @@ api.register(pwpolicy_del)
 
 class pwpolicy_mod(LDAPUpdate):
     """
-    Modify group password policy.
+    Modify a group password policy.
     """
     def pre_callback(self, ldap, dn, entry_attrs, attrs_list, *keys, **options):
         self.obj.convert_time_on_input(entry_attrs)
@@ -356,7 +358,7 @@ api.register(pwpolicy_mod)
 
 class pwpolicy_show(LDAPRetrieve):
     """
-    Display group password policy.
+    Display information about password policy.
     """
     takes_options = (
         Str('user?',
diff --git a/ipalib/plugins/rolegroup.py b/ipalib/plugins/rolegroup.py
index 9ff3ef775..99560c46c 100644
--- a/ipalib/plugins/rolegroup.py
+++ b/ipalib/plugins/rolegroup.py
@@ -20,36 +20,41 @@
 """
 Rolegroups
 
-A rolegroup is used for fine-grained delegation. Access control rules (ACIs)
-grant permission to performa a given task (add user, modify group, etc) to 
-task groups. Role groups are members of task groups, giving them permission
-to perform the task.
+A rolegroup is used for fine-grained delegation. Access control rules
+(ACIs) grant permission to perform given tasks (add a user, modify a group,
+etc.), to task groups. Rolegroups are members of taskgroups, giving them
+permission to perform the task.
 
-The logic looks like this:
+The logic behind ACIs and rolegroups proceeds as follows:
 
- ACI grants permission to taskgroup
+ ACIs grants permission to taskgroup
  rolegroups are members of taskgroups
- users, groups, hosts and hostgroups are members of role groups
+ users, groups, hosts and hostgroups are members of rolegroups
 
-A host/hostgroup may be members because you may want to perform
+Rolegroups can contain both hosts and hostgroups, enabling
 operations using the host service principal associated with a machine.
 
-A rolegroup may not be members of other rolegroups.
+Rolegroups can not contain other rolegroups.
 
 EXAMPLES:
 
- Create a new role group:
-   ipa rolegroup-add --desc="Junion level admin" junioradmin
+ Add a new rolegroup:
+   ipa rolegroup-add --desc="Junior-level admin" junioradmin
 
- Add this role to some tasks
+ Add this role to some tasks:
    ipa taskgroup-add-member --rolegroups=junioradmin addusers
    ipa taskgroup-add-member --rolegroups=junioradmin change_password
    ipa taskgroup-add-member --rolegroups=junioradmin add_user_to_default_group
 
+ Yes, this can seem backwards. The taskgroup is the entry that is granted
+ permissions by the ACIs. By adding a rolegroup as a member of a taskgroup
+ it inherits those permissions.
+
  Add a group of users to this role:
-   ipa rolegroup-add-member --groups=junioradmins junioradmin
+   ipa group-add --desc="User admins" useradmins
+   ipa rolegroup-add-member --groups=useradmins junioradmin
 
- Display this role group:
+ Display information about a rolegroup:
    ipa rolegroup-show junioradmin
 """
 
@@ -104,7 +109,7 @@ api.register(rolegroup)
 
 class rolegroup_add(LDAPCreate):
     """
-    Create new rolegroup.
+    Add a new rolegroup.
     """
 
     msg_summary = _('Added rolegroup "%(value)s"')
@@ -114,7 +119,7 @@ api.register(rolegroup_add)
 
 class rolegroup_del(LDAPDelete):
     """
-    Delete rolegroup.
+    Delete a rolegroup.
     """
 
     msg_summary = _('Deleted rolegroup "%(value)s"')
@@ -124,7 +129,7 @@ api.register(rolegroup_del)
 
 class rolegroup_mod(LDAPUpdate):
     """
-    Edit rolegroup.
+    Modify a rolegroup.
     """
 
     msg_summary = _('Modified rolegroup "%(value)s"')
@@ -146,7 +151,7 @@ api.register(rolegroup_find)
 
 class rolegroup_show(LDAPRetrieve):
     """
-    Display rolegroup.
+    Display information about a rolegroup.
     """
 
 api.register(rolegroup_show)
@@ -154,7 +159,7 @@ api.register(rolegroup_show)
 
 class rolegroup_add_member(LDAPAddMember):
     """
-    Add member to rolegroup.
+    Add members to a rolegroup.
     """
 
 api.register(rolegroup_add_member)
@@ -162,7 +167,7 @@ api.register(rolegroup_add_member)
 
 class rolegroup_remove_member(LDAPRemoveMember):
     """
-    Remove member from rolegroup.
+    Remove members from a rolegroup.
     """
 
 api.register(rolegroup_remove_member)
diff --git a/ipalib/plugins/service.py b/ipalib/plugins/service.py
index c9ae0b88e..50e8d54fd 100644
--- a/ipalib/plugins/service.py
+++ b/ipalib/plugins/service.py
@@ -19,44 +19,54 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
-Services (Identity)
+Services
 
-A service represents a running service on a host. This service record
-may store a kerberos principal or an SSL certificate (or both).
+A IPA service represents a service that runs on a host. The IPA service
+record can store a Kerberos principal, an SSL certificate, or both.
 
-A service may be managed directly by a machine, if it has been given
-the proper permission (even a machine other than the one the service is
-associated with). An example of this is requesting an SSL certificate
-using the host service principal credentials of the host.
+An IPA service can be managed directly from a machine, provided that
+machine has been given the correct permission. This is true even for
+machines other than the one the service is associated with. For example,
+requesting an SSL certificate using the host service principal credentials
+of the host. To manage a services using a host credentials you need to
+kinit as the host:
 
-Adding a service makes it possible to request an SSL certificate or
-keytab for that service but this is done as a separate step later. The
-creation of a service in itself doesn't generate these.
+ # kinit -kt /etc/krb5.keytab host/ipa.example.com@EXAMPLE.COM
 
-The certificate stored in a service is just the public portion. The
-private key is not stored.
+Adding an IPA service allows the associated service to request an SSL
+certificate or keytab, but this is performed as a separate step; they
+are not produced as a result of adding the service.
+
+Only the public aspect of a certificate is stored in a service record;
+the private key is not stored.
 
 EXAMPLES:
 
- Add a service:
+ Add a new IPA service:
    ipa service-add HTTP/web.example.com
 
- Allow a host to manage the service certificate:
+ Allow a host to manage an IPA service certificate:
   ipa service-add-host --hosts=web.example.com HTTP/web.example.com
   ipa rolegroup-add-member --hosts=web.example.com certadmin
 
- Remove a service:
+ Delete an IPA service:
    ipa service-del HTTP/web.example.com
 
- Find all services for a host:
+ Find all IPA services assicated with a host:
    ipa service-find web.example.com
 
  Find all HTTP services:
    ipa service-find HTTP
 
- Disable a service kerberos key:
+ Disable a service Kerberos key:
    ipa service-disable HTTP/web.example.com
 
+ Request a certificate for an IPA service:
+   ipa cert-request --principal=HTTP/web.example.com example.csr
+
+ Generate and retrieve a keytab for an IPA service:
+   ipa-getkeytab -s ipa.example.com -p HTTP/web.example.com -k /etc/httpd/httpd.keytab
+
 """
 import base64
 
@@ -161,7 +171,7 @@ api.register(service)
 
 class service_add(LDAPCreate):
     """
-    Add new service.
+    Add a new IPA new service.
     """
     msg_summary = _('Added service "%(value)s"')
     member_attributes = ['managedby']
@@ -209,7 +219,7 @@ api.register(service_add)
 
 class service_del(LDAPDelete):
     """
-    Delete an existing service.
+    Delete an IPA service.
     """
     msg_summary = _('Deleted service "%(value)s"')
     member_attributes = ['managedby']
@@ -246,7 +256,7 @@ api.register(service_del)
 
 class service_mod(LDAPUpdate):
     """
-    Modify service.
+    Modify an existing IPA service.
     """
     msg_summary = _('Modified service "%(value)s"')
     takes_options = LDAPUpdate.takes_options + (
@@ -282,7 +292,7 @@ api.register(service_mod)
 
 class service_find(LDAPSearch):
     """
-    Search for services.
+    Search for IPA services.
     """
     msg_summary = ngettext(
         '%(count)d service matched', '%(count)d services matched'
@@ -324,7 +334,7 @@ api.register(service_find)
 
 class service_show(LDAPRetrieve):
     """
-    Display service.
+    Display information about an IPA service.
     """
     member_attributes = ['managedby']
     takes_options = LDAPRetrieve.takes_options + (
@@ -370,7 +380,7 @@ api.register(service_remove_host)
 
 class service_disable(LDAPQuery):
     """
-    Disable the kerberos key of this service.
+    Disable the Kerberos key of a service.
     """
     has_output = output.standard_value
     msg_summary = _('Removed kerberos key from "%(value)s"')
diff --git a/ipalib/plugins/taskgroup.py b/ipalib/plugins/taskgroup.py
index e9e95448c..0ee90474d 100644
--- a/ipalib/plugins/taskgroup.py
+++ b/ipalib/plugins/taskgroup.py
@@ -20,11 +20,13 @@
 """
 Taskgroups
 
-A taskgroup is used for fine-grained delegation. Access control rules (ACIs)
-grant permission to performa a given task (add user, modify group, etc) to
-task groups. 
+A taskgroup enables fine-grained delegation of permissions. Access Control
+Rules, or instructions (ACIs), grant permission to taskgroups to perform
+given tasks such as adding a user, modifying a group, etc.
 
 A taskgroup may not be members of other taskgroups.
+
+See rolegroup and aci for additional information.
 """
 
 from ipalib.plugins.baseldap import *
@@ -79,7 +81,7 @@ api.register(taskgroup)
 
 class taskgroup_add(LDAPCreate):
     """
-    Create new taskgroup.
+    Add a new taskgroup.
     """
 
     msg_summary = _('Added taskgroup "%(value)s"')
@@ -89,7 +91,7 @@ api.register(taskgroup_add)
 
 class taskgroup_del(LDAPDelete):
     """
-    Delete taskgroup.
+    Delete a taskgroup.
     """
 
     msg_summary = _('Deleted taskgroup "%(value)s"')
@@ -99,7 +101,7 @@ api.register(taskgroup_del)
 
 class taskgroup_mod(LDAPUpdate):
     """
-    Modify taskgroup.
+    Modify a taskgroup.
     """
 
     msg_summary = _('Modified taskgroup "%(value)s"')
@@ -121,7 +123,7 @@ api.register(taskgroup_find)
 
 class taskgroup_show(LDAPRetrieve):
     """
-    Display taskgroup.
+    Display information about a taskgroup.
     """
 
 api.register(taskgroup_show)
@@ -129,7 +131,7 @@ api.register(taskgroup_show)
 
 class taskgroup_add_member(LDAPAddMember):
     """
-    Add member to taskgroup.
+    Add members to a taskgroup.
     """
 
 api.register(taskgroup_add_member)
@@ -137,7 +139,7 @@ api.register(taskgroup_add_member)
 
 class taskgroup_remove_member(LDAPRemoveMember):
     """
-    Remove member from taskgroup.
+    Remove members from a taskgroup.
     """
 
 api.register(taskgroup_remove_member)
diff --git a/ipalib/plugins/user.py b/ipalib/plugins/user.py
index f698aa703..5841d7a01 100644
--- a/ipalib/plugins/user.py
+++ b/ipalib/plugins/user.py
@@ -18,19 +18,23 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 """
-Users (Identity)
+Users
 
-Manage user entries.
+Manage user entries. All users are POSIX users.
+
+Locking a user account prevents that user from obtaining new Kerberos
+credentials. It does not invalidate any credentials that have already
+been issued.
 
 EXAMPLES:
 
- Create a new user:
+ Add a new user:
    ipa user-add --first=Tim --last=User --passwd tuser1
 
- Find a user Tim:
+ Find all users whose entries include the string "Tim":
    ipa user-find Tim
 
- Find all users with Tim as the first name:
+ Find all users with "Tim" as the first name:
    ipa user-find --first=Tim
 
  Lock a user account:
@@ -156,7 +160,7 @@ api.register(user)
 
 class user_add(LDAPCreate):
     """
-    Create new user.
+    Add a new user.
     """
 
     msg_summary = _('Added user "%(value)s"')
@@ -205,7 +209,7 @@ api.register(user_add)
 
 class user_del(LDAPDelete):
     """
-    Delete user.
+    Delete a user.
     """
 
     msg_summary = _('Deleted user "%(value)s"')
@@ -224,7 +228,7 @@ api.register(user_del)
 
 class user_mod(LDAPUpdate):
     """
-    Modify user.
+    Modify a user.
     """
 
     msg_summary = _('Modified user "%(value)s"')
@@ -246,7 +250,7 @@ api.register(user_find)
 
 class user_show(LDAPRetrieve):
     """
-    Display user.
+    Display information about a user.
     """
 
 api.register(user_show)
@@ -254,7 +258,7 @@ api.register(user_show)
 
 class user_lock(LDAPQuery):
     """
-    Lock user account.
+    Lock a user account.
     """
 
     has_output = output.standard_value
@@ -280,7 +284,7 @@ api.register(user_lock)
 
 class user_unlock(LDAPQuery):
     """
-    Unlock user account.
+    Unlock a user account.
     """
 
     has_output = output.standard_value