Document distributions in the 6.1 upgrade guide.

[mauritsvanrees]

See plone/Products.CMFPlone#3854

---

📚 Documentation preview 📚: https://plone6--1733.org.readthedocs.build/

[stevepiercy]

Here's an initial review. I have more work to do, so please do not merge until I have a chance. Thank you!

[stevepiercy]

Thanks for the docs! I edited them to clarify a few things, add a few enhancements, and style.

However I still have one critical concern that I firmly believe should be addressed prior to the final release of 6.1: there are no usage docs! I cannot stress enough the importance of this, and I hope my fellow Plonistas agree.

Aside from that, it would be good for several other pairs of eyes review my revisions.

[mauritsvanrees]

However I still have one critical concern that I firmly believe should be addressed prior to the final release of 6.1: there are no usage docs! I cannot stress enough the importance of this, and I hope my fellow Plonistas agree.

Just checking. What do you mean with "usage docs" in this case? Usage docs specifically for distributions, so how to create a new distribution and how to create a site with a distribution, integrating this with the installation docs? Or end user documentation of Plone as a whole?

[stevepiercy]

Just checking. What do you mean with "usage docs" in this case?

Specifically usage of plone.distribution, primarily for developers.

[stevepiercy]

BTW, the user manual is in a sad state, but at least we have a PLIP: plone/Products.CMFPlone#3987

[stevepiercy]

A couple of big concerns and questions, and the rest minor grammar fixes.

[davisagli]

@mauritsvanrees @stevepiercy This is the upgrade guide, so the audience is people who are upgrading an existing site, not creating a new one.

I think it would help if we break thing apart into a few different pages:

1. A conceptual guide "Plone distributions" which explains what a distribution is (i.e. this section from the plone.distribution readme: https://github.com/plone/plone.distribution/?tab=readme-ov-file#what-is-a-plone-distribution) and the packages in Plone that are related to distributions (i.e. lines 130-135 here)
2. A how-to guide "Create a Plone site" which shows how to add a Plone site to an existing instance (regardless of how it was installed). This can be adapted from lines 137-148 here. I think it should go in the new Admin Guide which I am working on in Start Admin Guide, revamp install/getting started #1746
3. A how-to guide "Create a Plone distribution" which explains how to create a new Plone distribution. This can be mostly copied from the plone.distribution readme. I think it should go in the new Developer Guide.
4. This section of the upgrade guide can focus on the optional changes that can be made to an existing site (i.e. lines 158-178 here.

I can help prepare these changes if they sound good. Let me know what you think.

[mauritsvanrees]

That sounds good to me.

[stevepiercy]

@davisagli yes, please! I was struggling with the content straddling multiple axes of the Diataxis Framework, and I think you got it all laid it.

[stevepiercy]

I've completed my review by pushing commits.

I made a few comments and asked some questions.

[stevepiercy]

@davisagli I've resolved merge conflicts and made a few changes. Would you please review it again?

[davisagli]

@stevepiercy LGTM.

[mauritsvanrees]

Thanks a lot for picking this up, @davisagli and @stevepiercy !