Updating in app documentation

src/cms/models.py

@@ -26,16 +26,12 @@ class Page(models.Model):
 
     name = models.CharField(
         max_length=300,
-        help_text="The relative URL path to the page, using lowercase "
-        "letters and hyphens. For example, a page about "
-        "research integrity might be “research-integrity”.",
+        help_text="The relative URL path to the page. This will appear after the slash (/) at the end of your journal's main URL in the link to this page. It cannot contain any capital letters, spaces or special characters.",
         verbose_name="Link",
     )
     display_name = models.CharField(
         max_length=100,
-        help_text="Name of the page, in 100 characters or fewer, "
-        "displayed in the nav and in the top-level heading "
-        "on the page (e.g. “Research Integrity”).",
+        help_text="The page title. This will display in the navigation bar and as the heading on your page. 100 characters maximum.",
     )
     template = models.CharField(
         blank=True,
@@ -45,22 +41,14 @@ class Page(models.Model):
     content = JanewayBleachField(
         null=True,
         blank=True,
-        help_text="The content of the page. For headings, we recommend "
-        "using the Style dropdown (looks like a wand) and "
-        "selecting a heading level from 2 to 6, as the display "
-        "name field occupies the place of heading level 1. "
-        "Note that copying and pasting from a word processor "
-        "can produce unwanted results, but you can use Remove "
-        "Font Style (looks like an eraser) to remove some "
-        "unwanted formatting. To edit the page as HTML, "
-        "turn on the Code View (<>).",
+        help_text="The content of your page. If you are copying and pasting this content from a word processor, you may need to use the 'remove formatting' tool or paste without formatting and then format as needed using this editor. For any headings, we recommend using heading level 2 or below, as the page display name will be classed as heading 1. You can access different heading levels by clicking 'Format' and going to 'Blocks'. To edit the page as HTML, "
+        "turn on the code view (<>).",
     )
     is_markdown = models.BooleanField(default=True)
     edited = models.DateTimeField(auto_now=timezone.now)
     display_toc = models.BooleanField(
         default=False,
-        help_text="When enabled this page will display a thinner reading pane "
-        "with a table of contents side bar.",
+        help_text="Tick this box to enable a sidebar showing a table of contents for your page based on the headers you have used.",
         verbose_name="Display table of contents",
     )
 
@@ -80,8 +68,7 @@ class NavigationItem(models.Model):
 
     link_name = models.CharField(
         max_length=100,
-        help_text="The text that will appear in the nav bar "
-        "(e.g. “About” or “Research Integrity”)",
+        help_text="The page title as it will display in the navigation bar.",
         verbose_name="Display name",
     )
     link = models.CharField(
@@ -107,7 +94,7 @@ class NavigationItem(models.Model):
     )
     is_external = models.BooleanField(
         default=False,
-        help_text="Whether the link is to an external website.",
+        help_text="Tick this box if you are linking to an external web page.",
     )
     sequence = models.IntegerField(
         default=99,
@@ -126,14 +113,14 @@ class NavigationItem(models.Model):
     has_sub_nav = models.BooleanField(
         default=False,
         verbose_name="Has sub navigation",
-        help_text="Whether this item has sub-nav items under it.",
+        help_text="Tick this box if you want to create a drop-down in your navigation bar from this item.",
     )
     top_level_nav = models.ForeignKey(
         "self",
         blank=True,
         null=True,
         verbose_name="Top-level nav item",
-        help_text="If this is a sub-nav item, which top-level item should it go under?",
+        help_text="If you want this to fall under an existing drop-down in your navigation bar, select which one it should fall under.",
         on_delete=models.CASCADE,
     )
     for_footer = models.BooleanField(

src/comms/models.py

@@ -52,9 +52,21 @@ class NewsItem(models.Model):
         "core.Account", blank=True, null=True, on_delete=models.SET_NULL
     )
 
-    start_display = models.DateField(default=timezone.now)
-    end_display = models.DateField(blank=True, null=True)
-    sequence = models.PositiveIntegerField(default=0)
+    start_display = models.DateField(
+        default=timezone.now,
+        help_text="If you want to schedule this news item in advance, select a date for it to be published. Otherwise, select today's date for it to publish immediately.",
+    )
+
+    end_display = models.DateField(
+        blank=True,
+        null=True,
+        help_text="If you want your news item to appear for a limited time only, select a date for it to stop displaying.",
+    )
+
+    sequence = models.PositiveIntegerField(
+        default=0,
+        help_text="This controls the order of news items in relation to one another.",
+    )
 
     large_image_file = models.ForeignKey(
         "core.File",
@@ -71,13 +83,12 @@ class NewsItem(models.Model):
         max_length=255,
         blank=True,
         null=True,
-        help_text="If you want a custom byline add it here. This will overwrite the display of the user who created "
-        "the news item with whatever text is added here.",
+        help_text="The name of this news item's author. If this section is left blank, the byline will credit you as the author.",
     )
 
     pinned = models.BooleanField(
         default=False,
-        help_text="Pinned news items will appear at the top of the news list",
+        help_text="Tick this box to pin this item to the top of your news list.",
     )
 
     objects = models.Manager()

src/core/homepage_elements/carousel/models.py

@@ -27,14 +27,14 @@ class Carousel(models.Model):
 
     exclude = models.BooleanField(
         help_text=_(
-            "If enabled, the selectors below will behave as an exclusion list",
+            "Tick this box to use the selection tables below as exclusion, rather than inclusion criteria. If this box is ticked, content selected below will be excluded from the carousel.",
         ),
         default=False,
     )
 
     latest_articles = models.BooleanField(
         default=False,
-        help_text="The carousel will display the latest published articles",
+        help_text="The carousel will display the latest published articles.",
     )
 
     # these fields contains a custom list of articles and article-like carousel objects for Mixed and News modes
@@ -47,7 +47,7 @@ class Carousel(models.Model):
 
     latest_news = models.BooleanField(
         default=False,
-        help_text="The carousel will display the latest published news items",
+        help_text="The carousel will display the latest published news items.",
     )
 
     # a selected news field
@@ -73,7 +73,7 @@ class Carousel(models.Model):
 
     current_issue = models.BooleanField(
         default=False,
-        help_text="Always include the current issue",
+        help_text="Always include the current issue.",
     )
 
     def get_items(self):

src/core/homepage_elements/popular/forms.py

@@ -18,22 +18,22 @@ def __init__(self, *args, **kwargs):
         self.fields["most_popular_time"].initial = most_popular_time
 
     most_popular = forms.BooleanField(
-        label="Display Most Popular Articles",
+        label="Display most popular articles",
         help_text="Displays the most popular articles.",
         required=False,
     )
     num_most_popular = forms.IntegerField(
-        label="Number of Most Popular Articles to Display",
-        help_text="Determines how many popular articles we should display.",
+        label="Number of most popular articles to aisplay",
+        help_text="Determines how many popular articles should be displayed.",
     )
     most_popular_time = forms.ChoiceField(
         choices=(
             ("weekly", "Weekly"),
             ("monthly", "Monthly"),
             ("yearly", "Yearly"),
         ),
-        label="Number of Most Popular Articles to Display",
-        help_text="Determines how many popular articles we should display.",
+        label="Number of most popular articles to display",
+        help_text="Determines how many popular articles should be displayed.",
     )
 
     def save(self, commit=True):

src/core/models.py

@@ -486,36 +486,36 @@ class Account(AbstractBaseUser, PermissionsMixin):
         max_length=40, null=True, blank=True, verbose_name=_("ORCiD")
     )
     twitter = models.CharField(
-        max_length=300, null=True, blank=True, verbose_name=_("Twitter Handle")
+        max_length=300, null=True, blank=True, verbose_name=_("Twitter handle")
     )
     facebook = models.CharField(
-        max_length=300, null=True, blank=True, verbose_name=_("Facebook Handle")
+        max_length=300, null=True, blank=True, verbose_name=_("Facebook handle")
     )
     linkedin = models.CharField(
-        max_length=300, null=True, blank=True, verbose_name=_("Linkedin Profile")
+        max_length=300, null=True, blank=True, verbose_name=_("Linkedin profile")
     )
     website = models.URLField(
         max_length=300, null=True, blank=True, verbose_name=_("Website")
     )
     github = models.CharField(
-        max_length=300, null=True, blank=True, verbose_name=_("Github Username")
+        max_length=300, null=True, blank=True, verbose_name=_("GitHub username")
     )
     profile_image = models.ImageField(
         upload_to=profile_images_upload_path,
         null=True,
         blank=True,
         storage=fs,
-        verbose_name=("Profile Image"),
+        verbose_name=("Profile image"),
     )
     email_sent = models.DateTimeField(blank=True, null=True)
     date_confirmed = models.DateTimeField(blank=True, null=True)
     confirmation_code = models.CharField(
         max_length=200,
         blank=True,
         null=True,
-        verbose_name=_("Confirmation Code"),
-        help_text="A UUID created upon registration and retrieved "
-        "for authentication during account activation",
+        verbose_name=_("Confirmation code"),
+        help_text="A Universally Unique Identifier (UUID) created upon registration and retrieved "
+        "for authentication during account activation.",
     )
     signature = JanewayBleachField(
         blank=True,
@@ -528,7 +528,7 @@ class Account(AbstractBaseUser, PermissionsMixin):
         blank=True,
         choices=tuple(),
         dynamic_choices=TIMEZONE_CHOICES,
-        verbose_name=_("Preferred Timezone"),
+        verbose_name=_("Preferred timezone"),
     )
 
     is_active = models.BooleanField(default=False)
@@ -537,11 +537,13 @@ class Account(AbstractBaseUser, PermissionsMixin):
 
     enable_digest = models.BooleanField(
         default=False,
-        verbose_name=_("Enable Digest"),
+        verbose_name=_("Enable digest"),
     )
     enable_public_profile = models.BooleanField(
         default=False,
-        help_text=_("If enabled, your basic profile will be available to the public."),
+        help_text=_(
+            "Tick this box to make your basic profile available to the public."
+        ),
         verbose_name=_("Enable public profile"),
     )
 
@@ -997,7 +999,7 @@ class Meta:
 class Role(models.Model):
     name = models.CharField(
         max_length=100,
-        help_text="Display name for this role (can include spaces and capital letters)",
+        help_text="Display name for this role (can include spaces and capital letters).",
     )
     slug = models.CharField(
         max_length=100,
@@ -1063,7 +1065,7 @@ def __repr__(self):
     ("public", "Public"),
     ("typesetters", "Typesetters"),
     ("proofreaders", "Proofreaders"),
-    ("copyeditors", "Copyedtiors"),
+    ("copyeditors", "Copyeditors"),
     ("editors", "Editors"),
     ("owner", "Owner"),
 )
@@ -1625,8 +1627,8 @@ class Galley(AbstractLastModifiedModel):
     # All Galleys
     label = models.CharField(
         max_length=400,
-        help_text='Typeset file labels are displayed in download links and have the format "Download Label" eg. if '
-        "you set the label to be PDF the link will be Download PDF. If you want Janeway to set a label for "
+        help_text="Typeset file labels are displayed in download links and have the format 'Download Label', e.g. if "
+        'you set the label to be "PDF", the link will be "Download PDF". If you want Janeway to set a label for '
         "you, leave it blank.",
     )
     type = models.CharField(max_length=100, choices=galley_type_choices())
@@ -1768,7 +1770,7 @@ class XSLFile(models.Model):
     date_uploaded = models.DateTimeField(default=timezone.now)
     label = models.CharField(
         max_length=255,
-        help_text="A label to help recognise this stylesheet",
+        help_text="A label to help recognise this stylesheet.",
         unique=True,
     )
     comments = JanewayBleachField(blank=True, null=True)
@@ -1833,7 +1835,7 @@ class Task(models.Model):
     link = models.TextField(
         null=True,
         blank=True,
-        help_text="A url name, where the action of this task can undertaken",
+        help_text="A URL name, where the action of this task can be undertaken.",
     )
     assignees = models.ManyToManyField(Account)
     completed_by = models.ForeignKey(
@@ -1918,7 +1920,7 @@ class EditorialGroup(models.Model):
     sequence = models.PositiveIntegerField()
     display_profile_images = models.BooleanField(
         default=False,
-        help_text="Enable to display profile images for this group.",
+        help_text="Tick this box to display the profile images for this group.",
     )
 
     class Meta:
@@ -1950,7 +1952,7 @@ class EditorialGroupMember(models.Model):
     sequence = models.PositiveIntegerField()
     statement = models.TextField(
         blank=True,
-        help_text="A statement of interest or purpose",
+        help_text="A statement of interest or purpose.",
     )
 
     class Meta:
@@ -2211,7 +2213,7 @@ class HomepageElement(models.Model):
     has_config = models.BooleanField(default=True)
 
     class Meta:
-        verbose_name_plural = "Homepage Elements"
+        verbose_name_plural = "Homepage elements"
         ordering = ("sequence", "name")
         unique_together = ("name", "content_type", "object_id")
 
@@ -2793,7 +2795,7 @@ class RORStatus(models.TextChoices):
         max_length=10,
         validators=[validate_ror_id],
         verbose_name="ROR ID",
-        help_text="Non-URI form of Research Organization Registry identifier",
+        help_text="Non-URI form of Research Organization Registry identifier.",
     )
     ror_status = models.CharField(
         blank=True,
@@ -2804,7 +2806,7 @@ class RORStatus(models.TextChoices):
     ror_record_timestamp = models.CharField(
         max_length=10,
         blank=True,
-        help_text="The admin.last_modified.date string from ROR data",
+        help_text="The admin.last_modified.date string from ROR data.",
     )
     website = models.CharField(
         blank=True,
@@ -3022,7 +3024,7 @@ class ControlledAffiliation(models.Model):
     )
     is_primary = models.BooleanField(
         default=False,
-        help_text="Each author or user can have one primary affiliation",
+        help_text="Each author or user can have one primary affiliation.",
     )
     start = models.DateField(
         blank=True,
@@ -3033,7 +3035,7 @@ class ControlledAffiliation(models.Model):
         blank=True,
         null=True,
         verbose_name="End date",
-        help_text="Leave empty for a current affiliation",
+        help_text="Leave empty for a current affiliation.",
     )
 
     class Meta:
@@ -3274,7 +3276,7 @@ def bulk_update_from_ror(self, ror_records):
 class Location(models.Model):
     name = models.CharField(
         max_length=200,
-        help_text="City or place name",
+        help_text="City or place name.",
         blank=True,
     )
     country = models.ForeignKey(