Plone 6 Documentation Update 2024-11-20 - Plone Sphinx Theme 1.0.1 released

stevepiercy · November 30, 2024, 2:37pm

Plone 6 Documentation has made tremendous strides forward since my last update.

First I want to personally thank all the people who have contributed since the last update in May 2024.

@1letter
@acsr
@danalvrz
@datakurre
@davisagli
@ebrehault
@erico
@erral
@Faakhir30
@fredvd
@FritzHoing
@gforcada
@ghnire
@giuliaghisini
@ichim-david
@iFlameing
@iRohitSingh
@jensens
@ksuess
@mauritsvanrees
@MAX-786
@MrTango
@nileshgulia1
@pbauer
@petschki
@pnicolli
@polyester
@sneridagh
@Tishasoumya-02
@wesleybl
@yurj

Apologies to anyone I missed.

Plone 6 Documentation now includes documentation for:

Documentation itself
Plone API
Plone REST API
Volto
Training
Plone Sphinx Theme
@plone/registry

Documentation is under very active development. Contributions via GitHub are welcome. Several members of the Documentation Team will be participating at the PloneConf 2024 Sprint November 30, both in person and remotely. It's a great way for first-timers to contribute. I hope to see you all participate.

Plone Sphinx Theme 1.0.1 released

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

I'd like to give a special shout out to @datakurre for updating sphinxcontrib-httpexample to be compatible with Plone Sphinx Theme so that we can continue to display REST API HTTP endpoint example requests and responses in an attractive and accessible manner.

All projects that use Plone Sphinx Theme now inherit features from Sphinx Book Theme and PyData Sphinx Theme. In addition, the following new features are now available.

sphinxcontrib.youtube allows you to embed remotely hosted videos from YouTube, Vimeo, or PeerTube using privacy mode.
sphinxcontrib.mermaid allows you to embed Mermaid graphs in your documents, including general flowcharts, sequence diagrams, and Gantt charts.
Vale upgraded to v3. It checks for American English spelling, grammar, syntax, and the Microsoft Developer Style Guide.

You can view the Plone Sphinx Theme's documentation.

Read the Docs for pull request previews

I switched from Netlify to Read the Docs for pull request preview builds of documentation. This saves the effort of checking out the pull request branch, and building the docs locally. Netlify supported only Python 3.8, and the parent theme for Plone Sphinx Theme requires Python 3.9 or greater. Read the Docs also has a long history of supporting Python and open source software by publishing their documentation at no cost.

New documentation

Continued to adapt documentation to use the Diátaxis Framework. Most of Plone 6 Documentation consists of How-to guides, with a few Conceptual guides (explanation), Reference guides, and Trainings (tutorials). We're working to disentangle and better present documentation so the reader can find what they need.
Created a Get started guide, with sections to try a Plone demo, install, learn more about, and contribute to Plone. It now guides you to choose a frontend and installation method according to your needs, helping you make an informed decision. Special thanks to @davisagli for leading the charge on this effort.
Created a new Admin guide, which will help you install, operate, and configure Plone.
Created a new space for Developer guides, which currently only includes Create a Plone distribution.
Created a new space for Conceptual guides. These guides help the reader gain a deeper and broader understanding of Plone.
Overhauled the Volto add-on documentation, breaking it into Developer guides and Conceptual guides. Special thanks to @sneridagh for this effort.
@plone/registry provides support for building an add-on and configuration registry with infrastructure for JavaScript and TypeScript-based apps. Special thanks to @sneridagh again for this effort.
coredev.buildout documentation migrated to Contributing to Plone 6 core.

Training

Two trainings were added and two others were updated.

Other major achievements

Most of the efforts continue to focus on improving the Plone developer experience. There is still a glaring omission of a comprehensive User Manual, but there is now a PLIP: Create User Manual with screenshots and videos for Plone 6 and plans to apply for grants to fund its development. See Apply for grants to fund Plone development and Google Season of Docs for 2024.

For the first time in about 5 years, the Documentation repository has fewer than 100 open issues, currently at 92, all of which apply to Plone 6. Including documentation from other projects, there are 123 open issues.

An impressive 238 documentation issues and pull requests were closed since my previous report.

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	4	65	5	1	396	471
volto	3	26	4	0	252	285
training	0	9	2	0	90	101
plone.restapi	0	1	0	0	64	65
plone-sphinx-theme	0	3	0	0	37	40
plone.api	0	2	0	0	22	24
training.plone.org	0	0	0	0	4	4
Products.CMFPlone	1	1	0	0	1	3
plone.volto	0	0	0	0	3	3
plone-backend	0	2	0	0	0	2
cookieplone	0	1	0	0	1	2
plone.app.discussion	1	0	0	0	0	1
cookieplone-templates	0	1	0	0	0	1
mockup	0	1	0	0	0	1
plone.app.dexterity	0	0	1	0	0	1
buildout.coredev	0	0	0	0	1	1
demo.plone.org	0	0	0	0	1	1
plone.staticresources	0	0	0	0	1	1
total	9	112	12	1	873	1007

A Burn up / CFD graph shows our progress since Jan 15, 2022. The pace of work being completed is fairly consistent.

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

Compare this graph to the maximum time frame, prior to current Documentation Team leadership.

Next steps

Continue migrating documentation to align with the Diátaxis Framework.
Secure funding for a User Manual, per PLIP: Create User Manual with screenshots and videos for Plone 6.
Migrate plone.app.dexterity docs into Plone 6 Documentation.
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.