Amend models based on @shaker comments

bakerydemo/base/models.py

@@ -30,9 +30,11 @@ class People(ClusterableModel):
     It uses the `@register_snippet` decorator to allow it to be accessible
     via the Snippets UI (e.g. /admin/snippets/base/people/)
 
-    `People` uses the `ClusterableModel`, which allows the relationship to another
-    model (e.g. a PageModel) to be stored independently of the database. This
-    allows us to preview ForeignKey relationships without first saving the parent
+    `People` uses the `ClusterableModel`, which allows the relationship with
+    another model to be stored locally to the 'parent' model (e.g. a PageModel)
+    until the parent is explicitly saved. This allows the editor to use the
+    'Preview' button, to preview the content, without saving the relationships
+    to the database.
     https://github.com/wagtail/django-modelcluster
     """
     first_name = models.CharField("First name", max_length=254)
@@ -100,7 +102,8 @@ class FooterText(models.Model):
 class StandardPage(Page):
     """
     A generic content page. On this demo site we use it for an about page but
-    it could be used for any type of page content.
+    it could be used for any type of page content that only needs a title,
+    image, introduction and body field
     """
 
     introduction = models.TextField(
@@ -328,9 +331,9 @@ class FormField(AbstractFormField):
     """
     Wagtailforms is a module to introduce simple forms on a Wagtail site. It
     isn't intended as a replacement to Django's form support but as a quick way
-    to generate a general purpose data-collection form without having to write
-    code. We use it on the site for a contact form. You can read more about
-    Wagtail forms at:
+    to generate a general purpose data-collection form or contact form
+    without having to write code. We use it on the site for a contact form. You
+    can read more about Wagtail forms at:
     http://docs.wagtail.io/en/latest/reference/contrib/forms/index.html
     """
     page = ParentalKey('FormPage', related_name='form_fields')

bakerydemo/blog/models.py

@@ -41,7 +41,7 @@ class BlogPeopleRelationship(Orderable, models.Model):
 
 class BlogPageTag(TaggedItemBase):
     """
-    This model allows us to creates a many-to-many relationship between
+    This model allows us to create a many-to-many relationship between
     the BlogPage object and tags. There's a longer guide on using it at
     http://docs.wagtail.io/en/latest/reference/pages/model_recipes.html#tagging
     """
@@ -123,10 +123,10 @@ class BlogPage(Page):
             ])
         return tags
 
-    # Defines parent to BlogPage as being BlogIndexPages
+    # Specifies parent to BlogPage as being BlogIndexPages
     parent_page_types = ['BlogIndexPage']
 
-    # Defines what content types can exist as children of BlogPage.
+    # Specifies what content types can exist as children of BlogPage.
     # Empty list means that no child content types are allowed.
     subpage_types = []
 
@@ -157,10 +157,10 @@ class BlogIndexPage(RoutablePageMixin, Page):
         ImageChooserPanel('image'),
     ]
 
-    # Defines that only BlogPage objects can live under this index page
+    # Speficies that only BlogPage objects can live under this index page
     subpage_types = ['BlogPage']
 
-    # Defines a function to access the children of the page (e.g. BlogPage
+    # Defines a method to access the children of the page (e.g. BlogPage
     # objects). On the demo site we use this on the HomePage
     def children(self):
         return self.get_children().specific().live()