Add chapter or section to admin guide on how to create a new backend add-on and how to include in backend

ksuess commented 2 weeks ago

Links of affected pages in Plone Documentation, if any.

https://6.docs.plone.org/admin-guide/index.html

Description

https://6.docs.plone.org/admin-guide/index.html is a well improved bundle of chapters, @davisagli Correct me if I am wrong, but I think it's missing a chapter on how to create a new backend add-on and how to include in backend. See https://training.plone.org/mastering-plone/voting-story/index.html#integrate-backend-package-in-training-setup where this is done.

davisagli commented 2 weeks ago

@ksuess My overall vision is that we should have two guides for different audiences:

Admin Guide is for people who are not developers but want to use the existing software (everything you need to know except for what can be done through the web, which should goes in the hypothetical User Guide)
Developer Guide will be for people who want to write new software (including customizations/extensions/addons)

So at least the way I've been thinking about it, this topic splits into 2 separate chapters:

A chapter in the Developer Guide on how to create a new add-on. @stevepiercy is creating a placeholder for this in https://github.com/plone/documentation/pull/1757 but it doesn't have the right content yet. The Classic UI folks would like to have docs about doing this with plonecli, so we might need 2 chapters, one about Cookieplone and one about plonecli.
A chapter in the Admin Guide on how to install a backend add-on from source. This is partly covered already in https://6.docs.plone.org/admin-guide/add-ons.html (look for the "Install an add-on from source" subheadings) but it doesn't cover installing from a local directory, and maybe the organization can be better since you didn't find it.

stevepiercy commented 2 weeks ago

A chapter in the Developer Guide on how to create a new add-on. @stevepiercy is creating a placeholder for this in https://github.com/plone/documentation/pull/1757 but it doesn't have the right content yet.

Yup.

The Classic UI folks would like to have docs about doing this with plonecli, so we might need 2 chapters, one about Cookieplone and one about plonecli.

@davisagli started the Cookieplone page, then ripped it out when the Classic UI folks showed no interest in its development. Then they realized there's a gaping hole for Plone backend add-ons, so I resurrected it, but again it missed the mark, although it wasn't clear to me what missed. It's in the now closed PR https://github.com/plone/documentation/pull/1753, which can be easily reopened and re-resurrected. It's not dead yet!

So that's the state of Plone 6 backend/Classic UI add-on documentation at this moment. PRs are welcome!

I don't have any suggestion for how to make Install Plone add-ons more visible at this time. In a future phase, we will evaluate better presentation of all guides, perhaps similar to NumPy's guides.

However we could do any of the following to improve its navigability, once the page is found.

We can add a tabbed interface to the existing https://6.docs.plone.org/admin-guide/add-ons.html#install-an-add-on, similar to what I did in this example: https://volto--6397.org.readthedocs.build/development/add-ons/install-an-add-on.html. But first I need to apply Plone Sphinx Theme to allow that tabbed interface. At this point, I think I can't wait any longer, and we'll just have to be happy with the default Sphinx search for now, instead of Nuclia search.
Add a contents directive to get a clear page contents visible. This may be somewhat redundant to the right-hand page navigation.
Append: "This chapter explains how to install add-ons as Python packages to extend the functionality of the Plone backend or Classic UI, depending on whether you used Cookieplone or Buildout to install your project.
Optionally add in-page labels for MyST {ref} targets, for Intersphinx links.

davisagli commented 2 weeks ago

@stevepiercy Actually I wasn't talking about changing where the "Install Plone add-ons" chapter is located. But I was wondering if we might want to take the content from the 2 "Install an add-on from source" subsections of that page, and turn them into a separate chapter, since installing from source is a bit of a different goal than installing from a release, and since it's easy to miss that both are covered in the "Install Plone add-ons" chapter.

stevepiercy commented 2 weeks ago

I thought it's a matter of using -e my_source in requirements.txt. What else is needed?

davisagli commented 2 weeks ago

@stevepiercy I was trying to point out this content that we already have:

for Cookieplone / mxdev: https://6.docs.plone.org/admin-guide/add-ons.html#install-an-add-on-from-source
for buildout: https://6.docs.plone.org/admin-guide/add-ons.html#id2

stevepiercy commented 2 weeks ago

Are you saying that installing from source belongs under the Developer guide and not the Admin guide, or that each should be duplicated into the Developer guide?

I can't recall any time I installed from source for anything other than development.

davisagli commented 2 weeks ago

@stevepiercy I was thinking that the info about installing from source should be moved to a new page in the Admin Guide, but it's arguable whether it belongs in the Admin Guide vs Developer Guide. Installing from source could be using a branch that someone else created (like a python3 compatibility branch of an add-on that hasn't gotten released for some reason) so I wasn't necessarily thinking of it as a development task, although it's likely most commonly done by developers.

stevepiercy commented 2 weeks ago

I don't think "Install Plone add-ons from source" merits its own page. Instead I would create includes that can be pulled into both the Admin and Developer guides, unless the process for installing from source is significantly different between these two audiences.

Given that @ksuess and @MrTango have both now mentioned installing something is now hard to find, and I myself thought that the installation process spans multiple audiences (and therefore guides) and doesn't really feel Administration-y to me, what do you think of breaking out a new Installation Guide from the Admin Guide? I'd prefer to move Demos, Learn, and Contribute stuff into https://6.docs.plone.org/index.html as that is not installation.

davisagli commented 2 weeks ago

the installation process spans multiple audiences (and therefore guides) and doesn't really feel Administration-y to me

For the purpose of deciding where things go, my definition of "administration" was anything having to do with setting up Plone that is not done through the web UI and not creating new software. You could say that installation spans multiple audiences or you could say that the developer audience also performs administrative tasks.

Anyway I don't have a strong feeling either way on your proposal. That might be a good way to go for where we cover installation of Plone and the other "get started" actions, and I wouldn't stand in the way of it.

We're a bit far afield from the topic of this issue, which was primarily about developing add-ons, not about installing Plone.

stevepiercy commented 2 weeks ago

Yes, we've wandered, but the discussion is still relevant toward resolving the original issue.

How to Admin isn't clear to me. How to Install, Develop, Operate, Deploy, or Contribute are more clear to me. That's a lot of guides, but maybe that's what we need for Plone, due to its layers of complexity.

Here's what I have in mind for Install guide items, not necessarily moving any of these items, but having a link to each of them.

Install guide

And do the same for anything development-y into the Develop guide.

Develop guide

Create a Plone distribution
Create a Plone backend add-on via Cookieplone (to be written)
Create a Plone backend add-on via plonecli (to be written)
Develop Volto add-ons

Thoughts? @davisagli @ksuess @MrTango

davisagli commented 2 weeks ago

@stevepiercy Let me sleep on it, but I don't hate it.

plone / documentation