Documentation: GSoD—Improve the clarity of new tutorial (#11357)

Clarified tutorial based on feedback

docs/tutorial/add_search.md

@@ -92,4 +92,4 @@ Now, you want to display your search across your site. One way to do this is to
 </header>
 ```
 
-Welldone! You now have a fully deployable portfolio site. The next section of this tutorial will walk you through how to deploy your site.
+Well done! You now have a fully deployable portfolio site. The next section of this tutorial will walk you through how to deploy your site.

docs/tutorial/create-footer_for_all_pages.md

@@ -16,10 +16,6 @@ python manage.py startapp base
 
 After generating the `base` app, you must install it on your site. In your `mysite/settings/base.py` file, add `"base"` to the `INSTALLED_APPS` list.
 
-```{note}
-You can structure your project in several ways aside from using a base app. For example, you can use your base app to manage configurations that are related or site-wide.
-```
-
 ## Create navigation settings
 
 Now, go to your `base/models.py` file and add the following lines of code:
@@ -207,7 +203,7 @@ class FooterText(
         verbose_name_plural = "Footer Text"
 ```
 
-In the preceding code, the `FooterText` class inherits from several `Mixins`, the `DraftStateMixin`, `RevisionMixin`, `PreviewableMixin`, and `TranslatableMixin`. In Django, `Mixins` are reusable pieces of code that defines additional functionality. They are implemented as Python classes, so you can inherit their methods and properties.
+In the preceding code, the `FooterText` class inherits from several `Mixins`, the `DraftStateMixin`, `RevisionMixin`, `PreviewableMixin`, and `TranslatableMixin`. In Django, `Mixins` are reusable pieces of code that define additional functionality. They are implemented as Python classes, so you can inherit their methods and properties.
 
 Since your `FooterText` model is a Wagtail snippet, you must manually add `Mixins` to your model. This is because snippets aren't Wagtail `Pages` in their own right. Wagtail `Pages` don't require `Mixins` because they already have them.
 
@@ -283,7 +279,7 @@ The `if` statement in the `get_footer_text` inclusion tag function checks whethe
 Finally, the function returns a dictionary containing the `"footer_text"` key with the value of the retrieved `footer_text` content.
 You'll use this dictionary as context data when rendering your `footer_text` template.
 
-To use the returned dictionary in, create a `templates/base/includes` folder in your `base` folder. Then create a `footer_text.html` file in your `base/templates/base/includes/` folder and add the following to it:
+To use the returned dictionary, create a `templates/base/includes` folder in your `base` folder. Then create a `footer_text.html` file in your `base/templates/base/includes/` folder and add the following to it:
 
 ```html+django
 {% load wagtailcore_tags %}

docs/tutorial/create_contact_page.md

@@ -69,7 +69,7 @@ class FormPage(AbstractEmailForm):
     ]
 ```
 
-In the preceding code, your `FormField` model inherits from `AbstractFormField`. With`AbstractFormField`, you can define any form field type of your choice in the admin interface. `page = ParentalKey('FormPage', on_delete=models.CASCADE, related_name='form_fields')` defines a parent-child relationship between the `FormField` and `FormPage` models.
+In the preceding code, your `FormField` model inherits from `AbstractFormField`. With `AbstractFormField`, you can define any form field type of your choice in the admin interface. `page = ParentalKey('FormPage', on_delete=models.CASCADE, related_name='form_fields')` defines a parent-child relationship between the `FormField` and `FormPage` models.
 
 On the other hand, your `FormPage` model inherits from `AbstractEmailForm`. Unlike `AbstractFormField`, `AbstractEmailForm` offers a form-to-email capability. Also, it defines the `to_address`, `from_address`, and `subject` fields. It expects a `form_fields` to be defined.
 

docs/tutorial/create_portfolio_page.md

@@ -98,7 +98,7 @@ class ImageBlock(StructBlock):
         template = "base/blocks/image_block.html"
 ```
 
-`ImageBlock` inherits from `StructBlock`. `ImageBlock`inherits from `StructBlock`. With `StructBlock`, you can group several child blocks together under a single parent block. Your `ImageBlock` has three child blocks. The first child block, `Image`, uses the `ImageChooserBlock` field block type. With `ImageChooserBlock`, editors can select an existing image or upload a new one. Its `required` argument has a value of `true`, which means that you must provide an image for the block to work. The `caption` and `attribution` child blocks use the `CharBlock` field block type, which provides single-line text inputs for adding captions and attributions to your images. Your `caption` and `attribution` child blocks have their `required` attributes set to `false`. That means you can leave them empty in your [admin interface](https://guide.wagtail.org/en-latest/concepts/wagtail-interfaces/#admin-interface) if you want to.
+`ImageBlock` inherits from `StructBlock`. With `StructBlock`, you can group several child blocks together under a single parent block. Your `ImageBlock` has three child blocks. The first child block, `Image`, uses the `ImageChooserBlock` field block type. With `ImageChooserBlock`, editors can select an existing image or upload a new one. Its `required` argument has a value of `true`, which means that you must provide an image for the block to work. The `caption` and `attribution` child blocks use the `CharBlock` field block type, which provides single-line text inputs for adding captions and attributions to your images. Your `caption` and `attribution` child blocks have their `required` attributes set to `false`. That means you can leave them empty in your [admin interface](https://guide.wagtail.org/en-latest/concepts/wagtail-interfaces/#admin-interface) if you want to.
 
 Just like `ImageBlock`, your `HeadingBlock` also inherits from `StructBlock`. It has two child blocks. Let's look at those.
 
@@ -140,7 +140,7 @@ Your `BaseStreamBlock` has four child blocks. The `heading_block` uses the previ
 
 Also, you defined a `Meta` class within your `ImageBlock` and `HeadingBlock` blocks. The `Meta` classes provide metadata for the blocks, including icons to visually represent them in the admin interface. The `Meta` classes also include custom templates for rendering your `ImageBlock` and `HeadingBlock` blocks.
 
-```note
+```{note}
 Wagtail provides built-in templates to render each block. However, you can override the built-in template with a custom template.
 ```
 
@@ -172,10 +172,7 @@ To add the custom template of your `HeadingBlock` block, create a `base/template
 ```{note}
 You can also create a custom template for a child block. For example, to create a custom template for `embed_block`, create a `base/templates/base/blocks/embed_block.html` file and add the following to it:
 
-```html+django
-{{ self }}
-```
-
+`{{ self }}`
 ```
 
 ## Use the blocks you created in your portfolio app

docs/tutorial/customize_homepage.md

@@ -77,9 +77,13 @@ class HomePage(Page):
 
 You might already be familiar with the different parts of your `HomePage` model. The `image` field is a `ForeignKey` referencing Wagtail's built-in Image model for storing images. Similarly, `hero_cta_link` is a `ForeignKey` to `wagtailcore.Page`. The `wagtailcore.Page` is the base class for all other page types in Wagtail. This means all Wagtail pages inherit from `wagtailcore.Page`. For instance, your `class HomePage(page)` inherits from `wagtailcore.Page`.
 
-Using `on_delete=models.SET_NULL` ensures that if you remove an image or hero link from your admin interface, the `image` and `hero_cta_link` fields on your Homepage will be set to null, preserving their data entries. Read the [Django documentation on the `on_delete` attribute](django.db.models.ForeignKey.on_delete) for more details.
+Using `on_delete=models.SET_NULL` ensures that if you remove an image or hero link from your admin interface, the `image` or `hero_cta_link` fields on your Homepage will be set to null, but the rest of the data will be preserved. Read the [Django documentation on the `on_delete` attribute](django.db.models.ForeignKey.on_delete) for more details.
 
-The `related_name` attribute creates a relationship between related models. For example, if you want to access the HomePage's `image` from `wagtailimages.Image`, you can use the `related_name` attribute. When you use `related_name="+"`, you create a connection between models that doesn't create a reverse relationship for your `ForeignKey` fields. In other words, you're instructing Django to create a way to access the HomePage's `image` from `wagtailimages.Image` but not a way to access `wagtailimages.Image` from the HomePage's `image`.
+By default, Django creates a reverse relation between the models when you have a `ForeignKey` field within your model. Django also generates a name for this reverse relation using the model name and the `_set` suffix. You can use the default name of the reverse relation to access the model with the `ForeignKey` field from the referenced model.  
+
+You can override this default naming behavior and provide a custom name for the reverse relationship by using the `related_name` attribute. For example, if you want to access your `HomePage` from `wagtailimages.Image`, you can use the value you provided for your `related_name` attribute.
+
+However, when you use `related_name="+"`, you create a connection between models without creating a reverse relation. In other words, you're instructing Django to create a way to access `wagtailimages.Image` from your `Homepage` but not a way to access `HomePage` from `wagtailimages.Image`.
 
 While `body` is a `RichTextField`, `hero_text` and `hero_cta` are `CharField`, a Django string field for storing short text.
 
@@ -102,7 +106,7 @@ To add content to your homepage through the admin interface, follow these steps:
 3. Click the **pencil**  icon beside **Home**.
 4. Choose an image, choose a page, and add data to the input fields.
 
-```Note
+```{note}
 You can choose your home page or blog index page to link to your Call to Action. You can choose a more suitable page later in the tutorial.
 ```
 

docs/tutorial/deployment.md

@@ -12,8 +12,8 @@ In this section of the tutorial, you'll use two platforms to deploy your site. Y
 
 You can use fly.io to host your site and serve your images. However, storing your images on a platform other than the one hosting your site provides better performance, security, and reliability.
 
-```note
-In this tutorial, you'll see yourname several times. Replace it with a name of your choice.
+```{note}
+In this tutorial, you'll see "yourname" several times. Replace it with a name of your choice.
 ```
 
 ## Setup Backblaze B2 Cloud Storage
@@ -141,7 +141,7 @@ DJANGO_CSRF_TRUSTED_ORIGINS=https://
 DJANGO_SETTINGS_MODULE=mysite.settings.production
 ```
 
-```note
+```{note}
 The Backblaze B2 storage uses _AWS_ and _S3_ because it works like Amazon Web Services’ S3.
 
 Do not commit or share your `.env.production `file. Anyone with the variables can access your site.
@@ -168,7 +168,7 @@ If your email verification fails, go to your Fly.io [Dashboard](https://fly.io/d
 
 5. Go to **Dashboard > Billing** and click **Add credit card** to add your credit card.
 
-```note
+```{note}
 Adding your credit card allows you to create a project in Fly.io. Fly.io won't charge you after adding your credit card.
 ```
 
@@ -196,8 +196,8 @@ On Windows, navigate to your project directory on **PowerShell**, activate your
 pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"
 ```
 
-```note
-If your get an error on Windows saying the term `pwsh` is  not recognized, install [PowerShell MSI](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.3#installing-the-msi-package) and then rerun the preceding Windows command.
+```{note}
+If you get an error on Windows saying the term `pwsh` is  not recognized, install [PowerShell MSI](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.3#installing-the-msi-package) and then rerun the preceding Windows command.
 ```
 
 7. [Sign in](https://fly.io/docs/hands-on/sign-in/) to your Fly.io by running the following command:
@@ -212,7 +212,7 @@ If you use Microsoft WSL, then run:
 ln -s /usr/bin/wslview /usr/local/bin/xdg-open
 ```
 
-```note
+```{note}
 If you successfully install flyctl but get an error saying "`fly` is not recognized" or "flyctl: command not found error", then you must add flyctl to your PATH. For more information, read [Getting flyctl: command not found error post install](https://community.fly.io/t/getting-flyctl-command-not-found-error-post-install/4954/1).
 ```
 
@@ -221,7 +221,7 @@ If you successfully install flyctl but get an error saying "`fly` is not recogni
 | Question | Instruction |
 | -------- | ------- |
 | Choose an app name | Enter a name of your choice. For example, _yourname-wagtail-portfolio_ |
-| Choose a region for deployment | Select the appropriate region. |
+| Choose a region for deployment | Select the region closest to the _AWS_S3_REGION_NAME_ in your _env.production_ file. |
 | Overwrite ".../.dockerignore"?  | Enter _y_ |
 | Overwrite ".../Dockerfile"?  | Enter _y_ |
 | Would you like to set up a Postgresql database now?  | Enter _y_ |
@@ -247,6 +247,8 @@ If you use a third-party app terminal like the Visual Studio Code terminal, you
 
 Now, you must configure your portfolio site for the final deployment.
 
+The `fly launch` command creates two new files, `Dockerfile` and `fly.toml`, in your project directory.
+
 Add the following to your `.gitignore` file to make Git ignore your environment files:
 
 ```
@@ -273,7 +275,7 @@ Also, check if your `fly.toml` file has the following:
   release_command = "python manage.py migrate"
 ```
 
-The `fly launch` command creates two new files, `Dockerfile` and `fly.toml`, in your project directory.
+Your `fly.toml` file should look as follows:
 
 ```toml
 app = "yourname-wagtail-portfolio"
@@ -443,6 +445,10 @@ Finally, deploy your site to Fly.io by running the following command:
 fly deploy --ha=false
 ```
 
+```{note}
+Running "fly deploy" creates two machines for your app. Using the "--ha=false" flag creates one machine for your app.
+```
+
 Congratulations! Your site is now live. However, you must add content to it. Start by creating an admin user for your live site. Run the following command:
 
 ```sh
@@ -455,7 +461,7 @@ Then run:
 DJANGO_SUPERUSER_USERNAME=username DJANGO_SUPERUSER_EMAIL=mail@example.com DJANGO_SUPERUSER_PASSWORD=password python manage.py createsuperuser --noinput
 ```
 
-```note
+```{note}
 Ensure you replace _username_, _mail@example.com_, and _password_ with a username, email address, and password of your choice.
 ```
 
@@ -476,6 +482,8 @@ All this while, you've been adding content to your site in the local environment
 If you encounter errors while trying to access your live site in your browser, check your application logs in your Fly.io Dashboard. To check your application logs, click **Dashboard > Apps > yourname-wagtail-portfolio > Monitoring**
 ```
 
+Congratulations! You made it to the end.
+
 ## Where next
 
 -   Read the Wagtail [topics](../topics/index) and [reference](../reference/index) documentation

docs/tutorial/set_up_site_menu.md

@@ -25,7 +25,7 @@ def get_site_root(context):
     return Site.find_for_request(context["request"]).root_page
 ```
 
-In the preceding code, you used the `get_site_root` template tag to retrieve the root page of your site, which is your HomePage. 
+In the preceding code, you used the `get_site_root` template tag to retrieve the root page of your site, which is your `HomePage` in this case. 
 
 Now, create `mysite/templates/includes/header.html` file and add the following to it:
 
@@ -83,7 +83,7 @@ Now, if you restart your server and reload your homepage, you'll see your site m
 
 ## Add pages to your site menu
 
-You can add any top-level page to the site menu by doing the following:
+You can add any top-level, like your Home page, Blog index page, Portfolio page, and Form page to the site menu by doing the following:
 1. Go to your admin interface.
 2. Go to any top-level page.
 3. Click **Promote**.

docs/tutorial/style_your_site.md

@@ -51,7 +51,7 @@ header {
 
 Now, reload your portfolio site to reflect the styles.
 
-```note
+```{note}
 If your webpage's styles do not update after reloading, then you may need to clear your browser cache.
 ```
 
@@ -134,7 +134,7 @@ In the preceding template, you made the following modifications:
 
 4. You wrapped the `{% block content %}` and `{% endblock %}` tags with a `<main>` HTML5 tag. The `<main>` tag is a semantic HTML5 tag used to indicate the main content of a webpage.
 
-Also, you should dynamically get your HomePage's title to use in your site menu instead of hardcoding it in your template. Also, you should include the child pages of the Home page in your site menu if they have their 'Show in menus' option checked. Finally, you want to ensure that you add the `wagtailuserbar` that you removed from your `base` template to your `header` template. This will improve users' experience for keyboard and screen reader users. 
+Also, you should dynamically get your HomePage's title to use in your site menu instead of hardcoding it in your template. You should include the child pages of the Home page in your site menu if they have their 'Show in menus' option checked. Finally, you want to ensure that you add the `wagtailuserbar` that you removed from your `base` template to your `header` template. This will improve users' experience for keyboard and screen reader users. 
 
 To make the improvements mentioned in the preceding paragraph, modify your `mysite/templates/includes/header.html` file as follows: