Index: /waeup/branches/ulif-rewrite/src/waeup/authentication.txt
===================================================================
--- /waeup/branches/ulif-rewrite/src/waeup/authentication.txt	(revision 4091)
+++ /waeup/branches/ulif-rewrite/src/waeup/authentication.txt	(revision 4092)
@@ -24,6 +24,30 @@
   >>> browser.handleErrors = False
 
-Accessing the front page
-========================
+Creating users (principals)
+===========================
+
+Before we can login, we have to provide a user (``principal`` in Zope
+terms). On the API level we can so by looking up a
+UserAuthenticationUtility named ``users``:
+
+  >>> from zope.component import getUtility
+  >>> from zope.app.authentication.interfaces import IAuthenticatorPlugin
+  >>> authenticator = getUtility(IAuthenticatorPlugin, name=u'users')
+
+This plugin also enables us to add new users. At least a username and
+a password is required:
+
+  >>> authenticator.addUser('bob', 'bobssecret')
+
+We can also add complete `Account` objects. An `Account` stores the
+user credentials and some metadata persistently:
+
+  >>> from waeup.authentication import Account
+  >>> alice = Account('alice', 'alicesecret')
+  >>> authenticator.addAccount(alice)
+
+
+Logging in via side bar
+=======================
 
 We can access the front page without restrictions:
@@ -33,5 +57,5 @@
   200 Ok
 
-There is a login form on the fron page sidebar:
+There is a login form on the front page sidebar:
 
   >>> 'form.login' in browser.contents
@@ -43,2 +67,3 @@
   >>> browser.getControl(name='form.password').value = 'grok'
   >>> browser.getControl('Login').click()
+
