Start Admin Guide, revamp install/getting started

[davisagli]

Changes in this PR:

• Create Admin Guide which will hold how-to guides related to installing, operating, configuring, and deploying Plone.
• Move existing install docs into the Admin Guide
• Create new install docs for buildout-based and pip-based installation of Classic UI, adapted from https://github.com/plone/documentation/pull/1701
• Turn /install/index.html into a "Get started" page that links into the admin guide as well as to other places for users with other goals.
• Move (and revise) existing Manage section into the Admin Guide
• Add redirects and update links for paths that changed

To do:

• [ ] Rebase on top of https://github.com/plone/documentation/pull/1749 once it has been reviewed

To do, but not a blocker for merging:

• [ ] Revise the Containers install section. Some of it should be rewritten to use docker-compose, and some of it is more reference material about the available images.

Not planned:

• Move the existing Deployment section into the Admin Guide (it mostly still needs to be written, but based on the outline it belongs under Conceptual Guides rather than as a how-to)

---

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

[stevepiercy]

I'd like more flattening. Take a look at the PyData Sphinx Theme docs. Note that PyData Sphinx Theme (PST) has navigation for each guide across the top, with headings (toctree captions) within each guide. I don't know whether the current theme supports that, but I can look into it. The new Plone Sphinx Theme supports it, as it is based on PST and Sphinx Book Theme (SBT), but it needs some work still with the Nuclia search. NumPy docs also has some interesting entry points and separation of guides.

You've set the stage for this kind of implementation, so the structure LGTM. I did not review content, just structure.

Before merging, we also need to implement redirects on the server to maintain SEO. sphinx_reredirects uses a meta refresh, but the server still sends an HTTP 200 OK. Pinging @polyester to be aware of this so it does not come as a surprise when we ask for this configuration. (I don't have access to do this.)

A very minor issue. There is a name conflict with "Admin". We have this new Admin and we have a Site Admin with a subset of admin tasks, specifically one who configures the settings of a Plone site through its web interface. Should we make a distinction for this new Admin, such as "Plone Admin" (too broad), "System Admin" (not bad), or something else?

[davisagli]

I'd like more flattening. Take a look at the PyData Sphinx Theme docs. Note that PyData Sphinx Theme (PST) has navigation for each guide across the top, with headings (toctree captions) within each guide. I don't know whether the current theme supports that, but I can look into it. The new Plone Sphinx Theme supports it, as it is based on PST and Sphinx Book Theme (SBT), but it needs some work still with the Nuclia search. NumPy docs also has some interesting entry points and separation of guides.

I don't object to that, but I'd suggest separating the task of reorganizing content into guides and the task of changing how those guides are presented in navigation. IMO there are also some pages that will always fall outside of guides (the Overview, the Get Started page, and the Glossary, at least). I wouldn't want merging this PR to be delayed just because we don't have a theme that supports doing this yet.

Before merging, we also need to implement redirects on the server to maintain SEO. sphinx_reredirects uses a meta refresh, but the server still sends an HTTP 200 OK. Pinging @polyester to be aware of this so it does not come as a surprise when we ask for this configuration. (I don't have access to do this.)

Ah okay, I didn't know about that, but it makes sense. @polyester what's the frontend webserver? I wonder if we could make it load some redirects from a file in this repository, so that it's easier to update. @stevepiercy I could also adjust things so that the existing content stays at the same URL (so that redirects aren't needed), but is listed in the new nav structure.

A very minor issue. There is a name conflict with "Admin". We have this new Admin and we have a Site Admin with a subset of admin tasks, specifically one who configures the settings of a Plone site through its web interface. Should we make a distinction for this new Admin, such as "Plone Admin" (too broad), "System Admin" (not bad), or something else?

I think in practice these are often the same person or group of people, so I don't see much of a conflict. Docs about configuring Plone through the UI probably need to go in the User Guide just because we'll have the Volto-vs-Classic UI distinction there, but we could include links to them from the Admin Guide.

[stevepiercy]

I don't object to that, but I'd suggest separating the task of reorganizing content into guides and the task of changing how those guides are presented in navigation. IMO there are also some pages that will always fall outside of guides (the Overview, the Get Started page, and the Glossary, at least). I wouldn't want merging this PR to be delayed just because we don't have a theme that supports doing this yet.

Sorry, I wasn't clear. I meant that this would be a second phase, after the initial reorganization, as this PR sets the stage for that presentation in the future.

OK on just "Admin".

[davisagli]

Sorry, I wasn't clear. I meant that this would be a second phase, after the initial reorganization, as this PR sets the stage for that presentation in the future.

Ok cool, I thought that was probably what you meant, but wanted to double check.

[davisagli]

@MrTango @1letter @petschki Does the reorganization of the install & admin docs here look okay from a Classic UI perspective?

[petschki]

Yes, I like the clear chapter approaches for each tech ... 👍🏼

[stevepiercy]

This PR depends on the merge of https://github.com/plone/volto/pull/6397 for Volto updates and reorganization.

[davisagli]

@stevepiercy Thanks for the review! I'm eager to get this merged too. There are some remaining todo items but they can be taken care of separately once other pieces are ready:

After https://github.com/plone/volto/pull/6397 is merged:

• [ ] Update link from docs/admin-guide/add-ons.md

After https://github.com/plone/documentation/pull/1749 is merged:

• [ ] Add link from /docs/install/index.md

After Plone 6.1 final release:

• [ ] Update docs/admin-guide/install-buildout.md and docs/admin-guide/install-pip.md to use Python versions for Plone 6.1

After updating to plone-sphinx-theme:

• [ ] Update _inc files that should use substitutions

[davisagli]

@stevepiercy Should I merge it?

[stevepiercy]

@davisagli yes, please do the merge honors. Representatives of both Classic UI and Volto Teams are on board.