diff --git a/docs/source/api/comment.txt b/docs/source/api/comment.txt
new file mode 100644
index 0000000..4d5cf79
--- /dev/null
+++ b/docs/source/api/comment.txt
@@ -0,0 +1 @@
+.. include:: ../../../plone/app/discussion/comment.txt
\ No newline at end of file
diff --git a/docs/source/api/conversation.txt b/docs/source/api/conversation.txt
new file mode 100644
index 0000000..a1c3ea4
--- /dev/null
+++ b/docs/source/api/conversation.txt
@@ -0,0 +1 @@
+.. include:: ../../../plone/app/discussion/conversation.txt
\ No newline at end of file
diff --git a/docs/source/api.txt b/docs/source/api/index.txt
similarity index 78%
rename from docs/source/api.txt
rename to docs/source/api/index.txt
index 6afad72..a7b72f8 100644
--- a/docs/source/api.txt
+++ b/docs/source/api/index.txt
@@ -1,5 +1,6 @@
-API/Interfaces
---------------
+===
+API
+===
 
 The conversation and replies adapters.
 
@@ -12,6 +13,9 @@ directly in reply to a particular comment (implemented by the CommentReplies
 adpater) or at the top level of the conversation (implemented by the
 ConversationReplies adapter).
 
-.. include:: ../../plone/app/discussion/conversation.txt
 
-.. include:: ../../plone/app/discussion/comment.txt
+.. toctree::
+   :maxdepth: 1
+
+   conversation.txt
+   comment.txt
diff --git a/docs/source/conf.py b/docs/source/conf.py
index d792a2a..d2a393e 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -3,7 +3,7 @@
 # plone.app.discussion documentation build configuration file, created by
 # sphinx-quickstart on Thu Mar 18 10:17:15 2010.
 #
-# This file is execfile()d with the current directory set to its containing dir.
+# This file is execfile()d with the current directory set to its containing dir
 #
 # Note that not all possible configuration values are present in this
 # autogenerated file.
@@ -11,23 +11,25 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys
+import os
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.append(os.path.abspath('.'))
 
-# -- General configuration -----------------------------------------------------
+# -- General configuration ----------------------------------------------------
 
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.doctest',
               'sphinx.ext.intersphinx',
               'sphinx.ext.todo',
               'sphinx.ext.coverage',
-              'repoze.sphinx.autointerface',]
+              'repoze.sphinx.autointerface'
+              ]
 
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/docs/source/index.txt b/docs/source/index.txt
index b5bfa4b..f09b01f 100644
--- a/docs/source/index.txt
+++ b/docs/source/index.txt
@@ -17,11 +17,10 @@ Contents:
    architecture.txt
    design.txt
    workflow.txt
-   comments.txt
    captcha.txt
    email-notification.txt
+   api/index.txt
    howtos/index.txt
-   api.txt
    changes.txt
 
 
diff --git a/plone/app/discussion/comment.txt b/plone/app/discussion/comment.txt
index 436b0e9..2a03ce2 100644
--- a/plone/app/discussion/comment.txt
+++ b/plone/app/discussion/comment.txt
@@ -1,7 +1,17 @@
+=======
 Comment
 =======
 
-.. literalinclude:: ../../plone/app/discussion/interfaces.py
+Member:
+
+    creator: username of the commenter (None for anonymous commenters).
+    author_name: full name of the commenter
+    author_email: email of the commenter
+
+    author_username: username of the commenter
+
+
+.. literalinclude:: interfaces.py
    :language: python
    :pyobject: IComment
 
diff --git a/plone/app/discussion/conversation.txt b/plone/app/discussion/conversation.txt
index d14a05c..5c03b7b 100644
--- a/plone/app/discussion/conversation.txt
+++ b/plone/app/discussion/conversation.txt
@@ -1,3 +1,4 @@
+============
 Conversation
 ============