search

plone / documentation

Plone Documentation
https://docs.plone.org
92 stars 154 forks source link

Start Admin Guide, revamp install/getting started #1746

Closed davisagli closed 2 weeks ago

davisagli commented 4 weeks ago

Changes in this PR:

To do:

To do, but not a blocker for merging:

Not planned:

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

stevepiercy commented 3 weeks ago

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 commented 3 weeks ago

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 commented 3 weeks ago

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 commented 3 weeks ago

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 commented 3 weeks ago

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

petschki commented 3 weeks ago

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

stevepiercy commented 2 weeks ago

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

davisagli commented 2 weeks ago

@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:

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

After Plone 6.1 final release:

After updating to plone-sphinx-theme:

davisagli commented 2 weeks ago

@stevepiercy Should I merge it?

stevepiercy commented 2 weeks ago

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