User guide
Dark Light

Contributing

On this page

We welcome all support for this User Guide, whether on bug reports, code, design, reviews, tests, documentation, translations or just feature requests.

Contributing

All of the User Guide pages are maintained in Wagtail. We use GitHub Discussions to coordinate content improvements, with features requests and bug reports for the site in the issue tracker.

Writing content

If you want to help with content, reach out to us in GitHub Discussions or on the #editor-guide channel of the Wagtail Slack workspace. We will then create an account for you in Wagtail, making sure you have access to the right parts of the content.

Translations

We want the guide to ultimately be available in as many languages as Wagtail itself. If you want to help with translations, start a thread in GitHub Discussions or join the #editor-guide channel of the Wagtail Slack workspace. We will then create an account for you in Wagtail, making sure you have access to the right parts of the content.

How to translate

We set up a separate translation team for each language, with their own Group able to submit changes to all pages and images in their locale. Translation teams reflect the changes in the “latest” version of the documentation, with legacy versions only being accessible to admin users.

For example, the Translators: Icelandic (latest) group has access to:

  • Translation: Can submit translations
  • Can access Wagtail admin: Yes
  • Pages: Notendahandbók Wagtail (latest homepage): Add, Edit, Lock, Unlock
  • Images: "Icelandic (latest)": Add, Edit, Choose

When working on changes to the "latest" source content in English, make sure to avoid unnecessarily removing and adding StreamField blocks, so block references are stable between revisions.

Versioning

Our default "latest" version of the guide corresponds to Wagtail’s last stable release. When Wagtail has a new release, we create a copy of the guide’s "latest" content for the stable version that’s no longer the latest. Here are the preliminary steps to do this:

  1. Make sure the version exists in the Django settings (WAGTAIL_GUIDE_VERSIONS).
  2. Add the new version in the CMS in Locales.
  3. Add the new version in the CMS in Collections – with a parent collection matching the version number, and then a child collection for any language with translated images (currently English only).

Page content

Then for every locale:

  1. Translate the "latest" homepage of the site (without child pages) to the new locale.
  2. Translate all child pages of the "latest" homepage (with child pages) to the new locale.
  3. For all pages of the new locale, manually publish changes for published pages only (page by page).
  4. Make sure to re-order the pages of the new locale as expected.

Images

First, use the "docs-screenshot" suite of wagtail-tooling to take new screenshots of the CMS with the bakerydemo project as the target. Screenshots all use standardized sizes, and a uniform style for highlights on the screen.

Then, upload the new images in the CMS:

  1. Bulk-move all images in the "English (latest)" collection to the new collection.
  2. Create a new copy of every image in the new collection, assigning it to the "English (latest)" collection
  3. Go through all "latest" pages of the site and update them to use the new copies of the images
  4. For all pages of the "latest" locale, manually sync translations (without publishing).
  5. For all "latest" locales, go through the pages and publish the ones that have no translations missing, so they use the latest images.