It's been over six months since I posted updates about Documentation and Trainings. We have some major updates to announce.
I want to personally thank all the people who contributed, and provided reviews and feedback: @avoinea, @cguardia, @danalvrz, @davisagli, @ericof, @erral, @jensens, @ksuess, @loechel, @mauritsvanrees, @MAX-786, @mrtango, @nileshgulia1, @pbauer, @Rudd-O, @SaiRev0, @sneridagh, @tiberiuichim, @toalba.
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, both in person and remotely. Heck, we might even release the Plone 6 Documentation before Plone 6.1 is released! (that's a lie)
Training
Training has undergone a major overhaul.
During the Documentation Sprint at PloneConf, we had a change of plans with Trainings. See the old plans at Kill off Hugo site for Training? - #3 by pbauer.
The Hugo site is gone, and its repository has been archived.
We can pretty up the new Trainings home page using the Sphinx extension sphinx-design. See Use sphinx-design to improve home page layout · Issue #671 · plone/training · GitHub.
Trainings have been curated. Older obsolete trainings are now archived on the branch 2022. Older trainings are now forever preserved at a new site, https://2022.training.plone.org/. Its content is automatically deployed from the 2022 branch. Going forward, a new archive will be added every year after the trainings at each PloneConf.
Dark mode
We have been unintentionally testing dark mode on a few of the repositories where we neglected to pin versions of Sphinx, sphinx_book_theme, and its parent theme pydata_sphinx_theme. Oopsie! With Trainings becoming the official test subject, we expect to roll out these changes to all the other repositories that build their own documentation, including the main Plone 6 Documentation and Plone REST API. Of course, you are welcome to adopt this Plone theme for any of your projects.
Other Major Achievements
- Removed Google Analytics tags, and replaced with, or install, Matomo for analytics for Training, Documentation, and plone.restapi.
Documentation
We have made strides toward incorporating more documentation from other Plone projects. This is a huge effort that requires subject matter experts.
- Add old upgrade guide, update it and integrate with new chapters.
- Added classic-ui/view and layers.
- Move Plone 6 documentation site from https://6-dev.docs.plone.org/ to https://6.docs.plone.org/.
- classic-ui/view and layers
- Add old upgrade guide, update it and integrate with new chapters
- Add documentation for setting environment variables in add-ons
- Replace sphinxcontrib-spellcheck with Vale
- Add simple first portlets section.
- Behavior chapter from scratch
- Add version switcher
- Fix linkcheckbroken #1396
- Overhaul Contributing to Documentation
- Port Volto installation docs into the main Plone 6 Installation docs.
- CSRF in Plone
- Converted rst to MyST from plone/buildout.coredev
- add documentation for switching color themes #1443
- Move plone.app.caching documentation to deployment/caching
- Align with coredev Plone Contributor Agreement with PR
Volto
- Add contributing branch policy information
- Include CHANGELOG.md in the documentation
- Document how to change the base font and the font for headings.
- Add description for different types of blocks - Volto User Manual has begun!
- Update makefile with Vale and fix linkcheckbroken - Improved spell, grammar, style, and link checking for better documentation.
- Add message about the status of Volto and Plone 6 Installation docs - Point to the main Install docs.
- docs additions for external add-ons usage
- Using Vale in CI for spellcheck
- Move developer guidelines to contributing #4665
plone.restapi
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 | 55 | 18 | 0 | 171 | 245 |
| volto | 0 | 18 | 1 | 0 | 103 | 122 |
| plone.restapi | 0 | 2 | 0 | 0 | 39 | 41 |
| plone.api | 0 | 2 | 0 | 0 | 15 | 17 |
| training | 0 | 7 | 1 | 0 | 41 | 49 |
| 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 | 1 | 87 | 20 | 0 | 378 | 487 |
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
Next steps
- Beethoven Sprint
- Plone 6 Docs Final Release Checklist
- Create a Contributing to Plone section
- Prepare for plone.app.dexterity docs
- 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.
- Join the "Plone Docs" Netlify Open Source Team. Please ask on Discord in the
#documentationchannel to become a member of the team.
Previous updates
- Plone 6 Documentation Update 2022-09-28 - Revised Install Plone 6 docs, i18n/l10n
- Plone 6 Documentation Update 2022-07-13 - Install Plone 6
- Plone 6 Documentation Update 2022-04-30 - plone.api incorporated
- Plone 6 Documentation Update 2022-03-29 - plone.restapi incorporated
- Plone 6 Documentation Update 2022-02-21
- Plone 6 Documentation adds Volto frontend docs, automatic deployments
- Plone 6 Documentation ready for contributions
