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 add install notes for classic ui, pip and buildout method #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 Start "Choose a user interface" conceptual guide #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 plone/volto#6397 for Volto updates and reorganization.

[stevepiercy]

I've completed my review by pushing commits. It would be good for a final review from all interested parties.

@plone/volto-team @plone/classicui-team it is important to get your review on each of your parts.

We have less than a month until PloneConf 2024, and we should get these critical pieces of the Plone 6.1 documentation finalized before the release of Plone 6.1 final. That would be a first, at least since I've been mucking about with Plone documentation!

Trainers also need this documentation to be published ASAP so that they can refer to it in their trainings. I've already seen several pull requests come through that will need to refer to the changes in this PR.

Finally, this is great stuff, @davisagli, moving things forward into a sensible structure. I greatly appreciate your work on this.

[ichim-david]

@stevepiercy gave it a quick read, it looks fine although I see there are still to-do items and other pull requests prerequisites. So much start backend backend start due to cookies lone starter :(

[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 plone/volto#6397 is merged:

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

After #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

[stevepiercy]

These revisions are good.

[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.