Working extensively with Wagtail CMS and the surrounding community, we have discovered a range of common pitfalls developers run into when beginning to deliver with Wagtail.
When we decided to adopt Wagtail as a technology, we had to make a bunch of these discoveries ourselves. As such, we have made an effort to compile a few basic thoughts that should help others when getting started with wagtail.
More Than a CMS
Wagtail is built on top of the popular Python web application framework Django. Wagtail identifies this early on but for developers who are not familiar with Django, or Python, they might not recognise how integrated that underlying framework is. All of the functionality that makes Django so popular is directly available in Wagtail, and is built upon by adding areas that allow Wagtail to function as a CMS. This means the documentation can be fragmented across multiple technologies.
Our take away from this is that developers should familiarise themselves with the basics of the technologies involved and be aware that documentation might be spread out across the technology stack. We found this to be especially true when on-boarding individuals who had developed similar workflows in other tech stacks. One moment you could be working with Wagtail specific fields, then you might need to refer to the Django docs for more in-depth documentation around the wide range of fields available or creating a custom field. The same sort of approach applies to almost all aspects of Wagtail, which is also what makes it so great.
Despite the Wagtail documentation being good, some of the resources were not quite where we expected to find them and appeared much later in the documentation than we would have liked. Wagtail is still building on adding resources to their Third Party Developer section in the advanced area of their docs which is worth checking out. Below is a list of a couple of resources we feel are useful when getting a foothold with Wagtail development.