diff --git a/docs/source/howtos/howto_extend_the_comment_form.txt b/docs/source/howtos/howto_extend_the_comment_form.txt
new file mode 100644
index 0000000..33b1724
--- /dev/null
+++ b/docs/source/howtos/howto_extend_the_comment_form.txt
@@ -0,0 +1,140 @@
+Comment Form
+============
+
+This document explains how to extend the plone.app.discussion comment form with
+additional fields in an add-on product.
+
+.. seealso::
+ * See the github collective for the source code of this howto:
+ https://github.com/collective/collective.example.commentextender/
+
+.. note::
+
+ This howto applies only to plone.app.discussion >= 2.0.4 and >= 1.1.1. Prior
+ versions will not store the extended fields on the comment.
+
+First, create a new plone package::
+
+ $ paster create -t plone my.commentextender
+
+Go to the main directory of the package (my.commentextender/my/commentextender)
+and create a new file commentextender.py containing the ICommentExtenderFields
+interface definition with an additional "website" field, a persistent
+CommentExtenderFields class to actually store the "website" value, a
+CommentExtenderFactory to create the CommentExtenderFields, and CommentExtender
+class to actually extend the default comment form with the field::
+
+ from persistent import Persistent
+
+ from z3c.form.field import Fields
+
+ from zope import interface
+ from zope import schema
+
+ from zope.annotation import factory
+ from zope.component import adapts
+ from zope.interface import Interface
+ from zope.publisher.interfaces.browser import IDefaultBrowserLayer
+
+ from plone.z3cform.fieldsets import extensible
+
+ from plone.app.discussion.browser.comments import CommentForm
+ from plone.app.discussion.comment import Comment
+
+ # Interface to define the fields we want to add to the comment form.
+ class ICommentExtenderFields(Interface):
+ website = schema.TextLine(title=u"Website", required=False)
+
+ # Persistent class that implements the ICommentExtenderFields interface
+ class CommentExtenderFields(Persistent):
+ interface.implements(ICommentExtenderFields)
+ adapts(Comment)
+ website = u""
+
+ # CommentExtenderFields factory
+ CommentExtenderFactory = factory(CommentExtenderFields)
+
+ # Extending the comment form with the fields defined in the
+ # ICommentExtenderFields interface.
+ class CommentExtender(extensible.FormExtender):
+ adapts(Interface, IDefaultBrowserLayer, CommentForm)
+
+ fields = Fields(ICommentExtenderFields)
+
+ def __init__(self, context, request, form):
+ self.context = context
+ self.request = request
+ self.form = form
+
+ def update(self):
+ # Add the fields defined in ICommentExtenderFields to the form.
+ self.add(ICommentExtenderFields, prefix="")
+ # Move the website field to the top of the comment form.
+ self.move('website', before='text', prefix="")
+
+.. seealso::
+
+ * See the plone.z3cform pypi page for more documentation about how to add,
+ hide, and reorder fields:
+ http://pypi.python.org/pypi/plone.z3cform#fieldsets-and-form-extenders
+
+Now register the CommentExtenderFactory and CommentExtender Classes we just
+created by adding the following lines to your configure.zcml::
+
+
+
+
+
+Create a new Plone instance, globally allow commenting, allow commenting on a
+content object and you will see a comment form with an additional "website"
+field.
+
+Since we do not only want to store the "website" value on the comments, but also
+to show these values for existing comments, we have to override the comments
+viewlet. The easiest way to do this is to use z3c.jbot.
+
+First, add z3c.jbot to the setup.py of the my.commentextender package::
+
+ install_requires=[
+ ...
+ 'z3c.jbot',
+ ],
+
+Next, create a new directory called "overrides" inside the my.commentextender
+package and register it together with z3c.jbot in your configure.zcml::
+
+
+
+ ...
+
+
+
+
+
+
+
+Copy plone.app.discussion/plone/app/discussion/browser/comments.pt to the
+overrides directory we just created and rename comments.pt to
+plone.app.discussion.browser.comments.pt.
+
+You can now add code to show the website attribute to the documentByLine::
+
+
+ ...
+
+
+
+
+
diff --git a/docs/source/howtos/index.txt b/docs/source/howtos/index.txt
new file mode 100644
index 0000000..7c2e86d
--- /dev/null
+++ b/docs/source/howtos/index.txt
@@ -0,0 +1,4 @@
+.. toctree::
+ :maxdepth: 2
+
+ howto_extend_the_comment_form.txt
diff --git a/docs/source/index.txt b/docs/source/index.txt
index 7d0d311..7d587c9 100644
--- a/docs/source/index.txt
+++ b/docs/source/index.txt
@@ -17,8 +17,10 @@ Contents:
architecture.txt
design.txt
workflow.txt
+ comments.txt
captcha.txt
email-notification.txt
+ howtos/index.txt
api.txt
.. include:: ../../CHANGES.txt