Plone 6 Documentation Update 2025-03-16

stevepiercy · March 16, 2025, 2:01pm

Plone 6 Documentation is gathering momentum since my last update.

First I want to personally thank all the people who have contributed pull requests since my last update in November 2024.

@1letter
@acsr
@ale-rt
@davisagli
@erral
@gforcada
@jensens
@ksuess
@libargutxi
@Manas-Kenge
@mauritsvanrees
@nileshgulia1
@petschki
@Pulkitxm
@rohnsha0
@sneridagh
@ujsquared
@yurj

Apologies to anyone I missed.

Documentation is under very active development. Contributions via GitHub are welcome. Several members of the Documentation Team will be participating at upcoming sprints, including the Bucharest Sprint, both in person and remotely. It's a great way for first-timers to contribute to Plone, because you all have a fresh perspective on things that us old-timers take for granted. I hope to see you all participate.

Only 13% of Plone 6 Documentation issues resolved at the release of Plone 6.1

I wish I could be happy about the release of Plone 6.1, but only 13% of Plone 6 Documentation issues were resolved at the time of its release. (It's crept up to 17% since then.) The lack of current and accurate documentation for Plone 6 is the single greatest barrier to entry for all audiences. This reflects extremely poorly upon Plone, where documentation is perceived as less than an afterthought.

Evidently placeholder pages and TODOs in the documentation have been ineffective to encourage contributions from content experts. Additionally these empty pages and TODOs make Plone look like an incomplete and unfinished product. As a result, I've created an issue where all these items will be removed from Plone 6 Documentation. An issue for each item will be created or updated, TODOs will be hidden from display on the page, and empty pages will be removed.

github.com/plone/documentation

Purge empty pages and todos

opened 11:00PM - 02 Mar 25 UTC

stevepiercy

01 type: bug

We've had empty pages and TODOs for over three years in Plone 6 Documentation, e…specially under the Backend section, but also under Deployment, Classic UI, Volto, and Contributing. The [Plone 6.1 milestone](https://github.com/plone/documentation/milestone/9) has only 17% of its issues completed _after_ the release of Plone 6.1. The lack of current and accurate documentation for Plone 6 is the single greatest barrier to entry for all audiences. This reflects extremely poorly upon Plone, where documentation is perceived as less than an afterthought. The following list of URLs are affected. Purge empty pages. A page is empty when either it has no content or its only content is a TODO. If there is no existing issue for the page, then create a new issue. All other pages in the list have content with at least one TODO. For these pages, preserve the TODO. If the TODO does not contain a link to an existing issue, then create a new issue and add its URL to the TODO, except for obsolete TODOs, such as Upgrading Plone 4.x to 5.0. Configure `conf.py` to hide the display of TODOs, changing code from the following... https://github.com/plone/documentation/blob/b4462a84bac18a56ea8a37390cd87b027e8b85bd/docs/conf.py#L381-L385 ...to the following. ```py # -- Options for sphinx.ext.todo ----------------------- # See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos todo_include_todos = False todo_emit_warnings = True todo_link_only = True ``` Ref: https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration - [ ] https://6.docs.plone.org/backend/annotations.html - [ ] https://6.docs.plone.org/backend/behaviors.html#built-in-behaviors below the table. TODO: Linked issue is complete. - [ ] https://6.docs.plone.org/backend/configuration-registry.html - [ ] https://6.docs.plone.org/backend/control-panels.html - https://github.com/plone/documentation/pull/1909 - [ ] https://6.docs.plone.org/backend/portal-actions.html#expressions TODO - [ ] https://6.docs.plone.org/backend/search.html TODO and empty headings - [ ] https://6.docs.plone.org/backend/security.html - [ ] https://6.docs.plone.org/backend/sending-email.html - [x] https://6.docs.plone.org/backend/subscribers.html - https://github.com/plone/documentation/pull/1918 - [ ] https://6.docs.plone.org/backend/traversal-acquisition.html - [ ] https://6.docs.plone.org/backend/upgrading/preparations.html#back-up-your-plone-site TODO - [ ] https://6.docs.plone.org/backend/upgrading/troubleshooting.html TODO - [ ] https://6.docs.plone.org/backend/upgrading/version-specific-migration/p4x-to-p5x-upgrade.html TODO - [ ] https://6.docs.plone.org/backend/users-groups.html - [ ] https://6.docs.plone.org/backend/vocabularies.html - [ ] https://6.docs.plone.org/backend/workflows.html - [x] https://6.docs.plone.org/backend/zodb.html - https://github.com/plone/documentation/pull/1894/ - [ ] https://6.docs.plone.org/classic-ui/forms.html multiple TODOs - [ ] https://6.docs.plone.org/classic-ui/templates.html - [ ] https://6.docs.plone.org/classic-ui/viewlets.html multiple TODOs - [ ] https://6.docs.plone.org/classic-ui/views.html multiple TODOs - [ ] https://6.docs.plone.org/conceptual-guides/components.html TODO - [ ] https://6.docs.plone.org/conceptual-guides/package-management.html#manage-frontend-node-js-packages TODO - [ ] https://6.docs.plone.org/contributing/core/plip-review.html#javascript TODO - [ ] https://6.docs.plone.org/contributing/documentation/themes-and-extensions.html and purge the extension from `conf.py` and possible PST. - [ ] https://6.docs.plone.org/deployment/caching/rulesets-and-caching-operations.html#no-caching-plone-app-caching-nocaching TODO - [ ] https://6.docs.plone.org/deployment/continuous-integration-and-deployment.html - [ ] https://6.docs.plone.org/deployment/index.html TODO - [ ] https://6.docs.plone.org/deployment/optimize-and-tune.html - [ ] https://6.docs.plone.org/deployment/orchestration.html - [ ] https://6.docs.plone.org/i18n-l10n/language-negotiation.html TODOs should be a warning. - [ ] https://6.docs.plone.org/i18n-l10n/translating-content.html#language-selector TODO - [ ] https://6.docs.plone.org/i18n-l10n/translating-text-strings.html TODO should be a warning. - [ ] https://6.docs.plone.org/plone.restapi/docs/source/usage/content.html multiple TODOs - [ ] https://6.docs.plone.org/volto/client/actions/database.html - [ ] https://6.docs.plone.org/volto/conceptual-guides/index.html add toctree - [ ] https://6.docs.plone.org/volto/contributing/react.html - [ ] https://6.docs.plone.org/volto/contributing/routing.html - [ ] https://6.docs.plone.org/volto/user-manual/blocks.html multiple TODOs - [ ] https://6.docs.plone.org/volto/user-manual/index.html @plone/volto-team @plone/restapi-team @plone/ci-team @plone/classicui-team @plone/marketing-communications @plone/documentation-team @plone/developers

It's not all bad news, and I have some hope that we'll do better in future releases. I am very pleased to see that the Plone 7 Roadmap puts documentation as its first priority. "If it ain't documented, it's broken." The Volto Team is totally on board.

PLIP: Plone 7 Documentation Layout, Structure, Theme, and Search to Improve Usability

This new Plone Improvement Proposal (PLIP) is the result of gaining experience and collecting feedback over the last three years about how to make Plone Documentation easier to use, to find relevant content, and to align with best documentation practices.

Work has already started, specifically in Plone Sphinx Theme. Feedback on the PLIP is welcome, especially on the organization of guides.

Plone Sphinx Theme 1.4.0 released

plone-sphinx-theme is a Sphinx theme for Plone 6 Documentation, Plone Training, and documentation of various Plone packages.

Recent releases add support for Python 3.13, and drops Python 3.9. Support for the versionremoved admonition was added. Documentation now has tooltips, an icon for external links, and other new features. The Contribute documentation was improved to make it easier for first-timers. See the complete change log.

You can view the Plone Sphinx Theme's documentation.

New Plone 6 Documentation home page UI

It's here at last! We have a pretty home page for Plone 6 Documentation.

This work lays part of the foundation for the PLIP mentioned above. Many thanks to @Manas-Kenge to leading the charge.

New documentation

There were 155 merged pull requests for Plone documentation since my last update.

Highlights include the following items.

Training

The trainings to retain for 2025 have been set. The following trainings will be retained for 2025.

All others will be archived under 2024.training.plone.org.

See Archive PloneConf 2024, prepare for PloneConf 2025 · Issue #907 · plone/training · GitHub for updates.

Plone Documentation project board and statistics

GitHub now supports slicing and grouping by attributes on its project boards. You can now view all documentation issues across all repositories, and filter by a given repository, to get the count of items for each status. This makes it easier to find documentation issues to work on for a given repository.

Plone Documentation project board

A Burn up / CFD chart shows our progress since January 15, 2022. The pace of work being completed has been fairly consistent, until November 2024 when there was an explosion of activity. Hundreds of issues and pull requests were completed, and the number of open items dropped.

Burn up / CFD chart since Jan 15, 2022

Next steps

PLIP: Plone 7 Documentation Layout, Structure, Theme, and Search to Improve Usability #4097
Continue migrating documentation to align with the Diátaxis Framework
Secure funding for a User Manual, per PLIP 3987: Create User Manual with screenshots and videos for Plone 6.
Create a Cookieplone entry in the Conceptual guide #1759
Purge empty pages and todos #1882
Migrate plone.app.dexterity docs into Plone 6 Documentation
Port GenericSetup docs #1754
Using the converted 5.2 documentation MyST files, fill in the remaining gaps in Plone 6 documentation

How to contribute

We have many open issues that need your help.