Create Development guide as a primary navigation item and entry point

[stevepiercy]

See #1714 (comment)

---

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

[stevepiercy]

The failing linkcheck was temporary and can be ignored.

[1letter]

@stevepiercy I'm not sure that the section "install" should really contain a chapter Create a project with Classic UI (stable release). As enduser i expect a tutorial "How can i install Plone" not "How can i create an addon". I know that are many overlappings between this two procedures.

But i missing a guide "Install Plone" like "Install wordpress". Insert the Disk, Click Play, Wait..., Start.... something like this ;-)

[stevepiercy]

@1letter as an end user, I do not install Plone. I only use the installed end product. I might try a demo or use an existing installation. Installation is for administrators, developers, and integrators only.

That said, our user manual is in a sad state for Plone 6. We have minimal Volto usage in https://6.docs.plone.org/volto/user-manual/ and a PLIP to Create User Manual with screenshots and videos for Plone 6. We can't port Plone 5 user manual documentation because it is broken and outdated.

Plone is not as easy to install as an app from Google Play, App Store, or download and drag-and-drop or double-click the installer. WordPress has an installation process that is designed for developers and which an end user would never follow. Hosting companies may have a One-Click Install button through their websites, but that's on a controlled system with full automation. Previous efforts along these lines, such as a unified installer or Plone in a box, have withered due to lack of support, maintenance, and updates.

[davisagli]

The above 2 lines are about how to contribute to Plone itself, not how to develop your own projects based on Plone. They belong in the "Contributing to Plone" section, not the development guide.

There's a bunch of other stuff that should go in a development guide... how to use ZCML, GenericSetup, write content type schemas, register views, register API services, the various topics under https://6.docs.plone.org/volto/development/index.html ... should we try to tackle some of that now, or just merge this info on tests as the first step, and then continue later?

[stevepiercy]

Yeah, the testing standards are higher for contributing, but what else do we have to demonstrate how to write and run tests?

I will add empty headings for the stuff you mentioned, create issues for each to expose our needs, and add a todo in the docs with a link to the issue for each thing. Please feel free to list other concepts, and I'll add them. I'm fine with creating the outline, and adding content as time allows.

[stevepiercy]

I added a few headings and references for the backend to get us started.

I think that the much of the content in the Backend folder will eventually end up under Development as a subdirectory. After that is done, I would break out the explanation and other non-how-to content into an appropriate section.

[davisagli]

But i missing a guide "Install Plone" like "Install wordpress". Insert the Disk, Click Play, Wait..., Start.... something like this ;-)

@1letter In my opinion, that's a trap. Any real Plone site is going to require some customization to the frontend, backend, or both. So the idea with documenting how to create a project is that we try to get people started on a path where they have everything they need to configure/customize and deploy their Plone site, without needing to start over using a different installation approach.

(Maybe I'm too stuck in my world as a consultant and there are still people who just want to install Plone on a server and run it without customizing anything?)

I agree it's confusing that "Create a project with Classic UI (stable release)" currently uses a template that has naming related to addons. I'd like to change that: plone/cookieplone-templates#61

[1letter]

@stevepiercy I will not rant, i see the effort by you, that is a big challange to document the Plone universe. Sorry i lost the overview, 'Development guide','Backend','Classic UI'... that is to much for me. I don't see a strict way to consolidate these topics. More and more points where the possibilty exists to produce content that are double quantity.
What ist the Goal of the docs? "Write down all with examples" or should this a guide for a specific target group?

[stevepiercy]

@1letter the primary goal is to accurately document how to develop Plone 6. I'd say target developers. We can work on other audiences when there are people interested in writing documentation for those audiences.

Plone 5 docs are full of good, yet sometimes inaccurate or outdated material, that we could not publish for Plone 6. There has been a huge and successful effort by many contributors to get the Backend section ported to Plone 6. Where there are gaps, we can refer to Plone 5 docs, with a warning that it hasn't been updated for Plone 6, until it gets rewritten for Plone 6.

Setting aside content and turning to organization, the Diataxis framework organizes documentation into four categories. It's been adopted by hundreds of projects, including Python. The organization of content just moves bits of content around. Plone documentation is gradually moving toward this framework.

Within the context of Diataxis, Plone 6 Documentation today is mostly a collection of How-to guides for developers. There are some parts that are Explanation mixed in the How-to guides, and a few Reference parts such as REST API Endpoints and plone.api methods and descriptions, and all Tutorials are in Training.

Hope that helps explain where we are and headed with Documentation. Please ask for clarification.