A new tutorial series for the new year
I helped create a new tutorial series for Wagtail. Come try it out!
As we step into the new year, I’m excited to share our latest addition to the developer documentation—a new tutorial series. The new tutorial series builds on the existing Getting started tutorial. We created the series to address some of the challenges faced by new Wagtail users. These challenges include:
- An incomplete initial learning experience: We realized our existing Getting Started tutorial didn't give new users enough guidance for learning how to build a deployable website with Wagtail. Our "First 30 minutes of Wagtail" section in the 2023 product vision identified this challenge. Additionally, third-party tutorials tend to become outdated very quickly.
- Deployment challenges: Another challenge our users face is deployment. We learned this from informal feedback and our own experiences. We confirmed more specific challenges in our 2023 Wagtail deployment survey.
- Lack of reliable learning resources: Finally, there aren't many reliable resources we can send to people who are new to tech. Developers in our community are regularly involved with initiatives like Google Summer of Code, Outreachy, and Django Girls. We need reliable and well-maintained learning material that’s approachable for newcomers.
To address these challenges, the new tutorial series equips new users with step-by-step instructions to convert the blog site they built with the Getting Started tutorial into a fully deployable portfolio site. Also, it teaches new users how to implement some advanced Wagtail features.
Now let’s dive into the exciting features introduced by the tutorial!
Wagtail StreamField
One important Wagtail feature that new users may find hard to understand is StreamField. The existing Getting Started tutorial didn't show how to implement this. So we decided to teach users how to use it in the new tutorial series. We also explained what StreamField is and the rationale behind its development.
In the tutorial, users will use StreamField to create a portfolio page for their resume or Curriculum Vitae (CV).
Snippets integration
The new tutorial series demonstrates how users can add footer text to their portfolio site using Wagtail Snippets. Wagtail Snippets are used to add authors to the blog in the Getting started tutorial. However, this new series shows people a more advanced implementation. Also, unlike the Getting Started tutorial, the new tutorial provides a deeper explanation of the underlying code.
Wagtail Forms
We showed users how to add a contact page to their portfolio by using Wagtail Forms. We also took an opportunity to explain the differences between AbstractFormField and AbstractEmailForm.
Search functionality and pagination
Search is very important for any Wagtail site. So, we made sure the tutorial showed users how they can customize their built-in search app. The instructions to set up the search feature also show users how they can paginate their search results.
Deployment
Deploying Wagtail applications remains a challenging aspect for both new and existing users. We conducted a survey to understand where Wagtail users prefer to deploy their applications. The survey also asked users what cloud hosting services they want Wagtail to partner with. DigitalOcean was the most popular choice. AWS came in second, Google Cloud came in third while Fly.io and Vercel came in fourth and fifth, respectively.
Consequently, we decided to create a tutorial on how to deploy to Fly.io due to its simpler configuration and generous free tier. We also opted to use Backblaze to serve the site images for the same reasons.
However, there are still some challenges with deploying to Fly.io on Windows. On the bright side, we’re already working with the Fly.io team to fix this as soon as possible.
We look forward to you trying the tutorial and leaving some feedback. You can check a sample live site built from following the tutorial here.
Funding for this new tutorial series was generously provided by Google through the Google Season of Docs program. Thank you so much to everyone at Google who has supported us throughout this project.
