Plone 6 Documentation Update 2023-05-12 - Plone 6 Documentation released

Documentation
, ,
1

I have an important announcement for all contributors to Plone 6 Documentation.

First I want to personally thank all the people who recently contributed, and provided reviews and feedback: @davisagli, @fredvd, @jensens, @ksuess, @polyester, @sneridagh.

This project is under very active development. Contributions are welcome. Read more for how to participate. Several members of the Documentation Team will be participating at the Beethoven Sprint May 15-19, both in person and remotely. I hope to see you all participate.

Plone 6 documentation is now officially released

The default URL for documentation, https://docs.plone.org/, will now redirect to the latest version of documentation for Plone, currently https://6.docs.plone.org/. Previously there was no redirect, and often other Plone projects' documentation would link to files that were removed or moved from earlier versions. Authors will need to link to a specific version of Plone documentation.

Along with this change, the new default branch for Plone documentation is 6.0. Previously it was 6-dev.

Training

As a result of last month's Training curation, any links to the archived trainings must be updated by prefixing them with 2022. and updating Intersphinx references accordingly. Links that go to obsolete trainings will result in a 404 not found response, for example, https://training.plone.org/sad-trombone.

To update links in your documentation's Intersphinx setting in conf.py:

intersphinx_mapping = {
    "plone": ("https://6.docs.plone.org/", None),
    "python": ("https://docs.python.org/3/", None),
    "training": ("https://training.plone.org/", None),
    "training-2022": ("https://2022.training.plone.org/", None),  # Archived trainings
}

And in your MyST markdown, you would use a reference with the new Intersphinx mapping.

An alternative is `transmogrifier` (see the training {ref}`training-2022:transmogrifier-label`).

To recap, older trainings are now archived on the branch 2022, which is now published at a new site, https://2022.training.plone.org/. Going forward, a new archive will be added every year after each PloneConf, corresponding to that year.

Dark mode and new Plone Sphinx theme

With Training adopting dark mode in its Sphinx theme, we realized that updating all the repositories that use a customized version of Sphinx Book Theme is unsustainable. We would have to manually edit Jinja2 templates and copy over static assets.

To address this issue, a new Sphinx theme for Plone is under development, plone-sphinx-theme. The repository is currently empty, but will be updated during the Beethoven Sprint. When it is released, you can add this package to your dependencies, and configure your Sphinx documentation to use it as your theme, basking in the glory and brilliance of Plone's branding and identity.

Other Major Achievements

Documentation

Volto

Training

demo.plone.org

Project Board item counts

Here are our current counts on the Release Plone 6 docs project board.

Repository New Todo In Progress Approved Done Total
documentation 1 54 15 0 178 248
volto 0 18 1 0 109 128
plone.restapi 0 2 0 0 39 41
plone.api 0 2 0 0 15 17
training 1 7 1 0 43 51
plone-backend 0 2 0 0 0 2
plone.app.dexterity 0 0 1 0 0 1
buildout.coredev 0 1 0 0 0 1
training.plone.org 0 0 0 0 4 4
plone.volto 0 0 0 0 3 3
demo.plone.org 0 0 0 0 1 1
plone.staticresources 0 0 0 0 1 1
total 2 86 17 0 393 498

A Burn up / CFD graph shows our progress since Jan 15, 2022. The pace of work being completed is fairly consistent, whereas the number of In Progress (abandoned?) and Todo issues and pull requests increased.

https://github.com/orgs/plone/projects/12/insights/1

Burn up / CFD graph since Jan 15, 2022
Burn up / CFD graph since Jan 15, 20221179×616 64 KB

Next steps

How to contribute

  • We have many open issues that need your help.
  • Join the "Plone Docs" Netlify Open Source Team. Please ask on Discord in the #documentation channel to become a member of the team.

Previous updates

5 Likes
2

Thanks for work, but all search results in a search engine like google ends on the plone 6 documentation site with a hint to use https://5.docs.plone.org/. I think this is not optimal. I see the dilemma with the old and new url's. But why go the redirect to Plone 6 Docs?

Example:

  1. Search Term Plone api user
  2. Search Engine link to https://docs.plone.org/develop/plone.api/docs/user.html
  3. It ends on https://6.docs.plone.org/ but not on: https://5.docs.plone.org/develop/plone.api/docs/user.html

It's a little bit pity....

3

Thanks for the feedback. This plan was originally created back in January 2022, with some revisions, and always seeking feedback. I apologize if I was not transparent or communicated the plan sufficiently, and welcome suggestions for improvement. I encourage everyone who cares about documentation to participate.

We will add redirects for docs.plone.org/old-foo to 6.docs.plone.org/new-foo, which will accelerate search engine results updates. Search engine results will take some time to update, of course, as crawlers take their own sweet time to get around to it. If you have a specific redirect that should be prioritized, please create a new issue in Plone 6 documentation, specifying the old URL and new URL.

For example:

https://docs.plone.org/develop/plone.api/docs/user.html

should redirect to:

https://6.docs.plone.org/plone.api/user.html

In any case, this was a necessary step toward better search engine results, reducing link rot, and better documentation organization. Together we'll continue to improve documentation.

1 Like
4

I've opened an issue for further discussion:

5

This is now done. Try it out for any plone.api docs.

The remaining URLs will now redirect from:

https://docs.plone.org/foo.html

to:

https://6.docs.plone.org/foo.html

If the page exists, you're done. If it does not exist, a message explains what happened and suggests a search.

If you have further comments, please append to the open issue in plone/documentation:

Create redirects of docs.plone.org to 6.docs.plone.org