Index: /waeup/branches/ulif-rewrite/src/waeup/university/faculty.txt
===================================================================
--- /waeup/branches/ulif-rewrite/src/waeup/university/faculty.txt	(revision 4157)
+++ /waeup/branches/ulif-rewrite/src/waeup/university/faculty.txt	(revision 4157)
@@ -0,0 +1,69 @@
+Faculties
+*********
+
+:Test-Layer: unit
+
+Creating faculties
+==================
+
+We can create faculties:
+
+    >>> from waeup.university.faculty import Faculty
+    >>> myfaculty = Faculty()
+    >>> myfaculty
+    <waeup.university.faculty.Faculty object at 0x...>
+
+Another way to create faculties is by asking for a factory called
+``waeup.Faculty``. Before we can do this, we have to grok the `waeup`
+package. This happens automatically in real-world use:
+
+    >>> import grok
+    >>> grok.testing.grok('waeup')
+
+Now we can create a factory without importing a class:
+
+    >>> from zope.component import createObject
+    >>> myfaculty = createObject(u'waeup.Faculty')
+    >>> myfaculty
+    <waeup.university.faculty.Faculty object at 0x...>
+
+Faculty attributes
+==================
+
+Faculties have the attributes required by the `IFaculty` interface:
+
+    >>> from waeup.interfaces import IFaculty
+    >>> IFaculty.providedBy(myfaculty)
+    True
+
+    >>> from zope.interface.verify import verifyObject
+    >>> verifyObject(IFaculty, myfaculty)
+    True
+
+Each of the following attributes is mandatory.
+
+`title`
+-------
+
+Each faculty has a title:
+
+    >>> myfaculty.title
+    u'Unnamed Faculty'
+
+`title_prefix`
+--------------
+
+Each faculty has a title prefix, which specifies the kind of
+institution:
+
+    >>> myfaculty.title_prefix
+    u'faculty'
+
+`code`
+------
+
+Each faculty holds a code, which might be a shortcut or abbreviation
+of the real faculty name. By default the code is ``None``:
+
+    >>> myfaculty.code is None
+    True
