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.

[MrTango]

Is the goal to move all development docs under this navigation item?
So that we have a user and/or installation documentation item next to it?
If so we have to keep it really clean and avoid confusion.
I always found it hard to understand in the old docs, is this the area where i find info's how to develop things with Plone or for Plone (core development). For me there are this too areas in developing. Development and Contributing to Plone Core.
The later of course is a brother area nowadays with the Python and JS/Node stack.
@davisagli +1 for the renaming of just frontend to Volto ui, this would make things much more clear to people.

Other than that, let's keep things as flat as possible, so that we don't end up like with the Plone 5 docs, to deeply nested.
When i want to find something or to add something, i need to know directly where to find or put it.

[stevepiercy]

Is the goal to move all development docs under this navigation item?

@MrTango no. The ultimate goal is to structure documentation aligned with the Diataxis Framework. Currently development docs are a mixture of How-To Guides, Explanation (Conceptual Guide), and Reference, making them difficult to navigate and use.

So that we have a user and/or installation documentation item next to it?

We don't have a Plone 6 User Manual! When it gets written, it would be a How-To Guide. There would be two of these, one each for Volto and Classic UI.

Here's a simplified road map.

---

How-To Guides

• Install
• Develop
• User
  • Volto
  • Classic UI

Reference Guides

(Only the API reference parts, not the narrative parts, which would go under How-To or Conceptual guides.)

• Plone REST API
• plone.api

Conceptual guides

• Package management
• make build-backend details

Tutorials

• Training

---

Regarding your other comments, I totally agree, and that's why I am convinced that following the Diataxis Framework will prevent all the problems ignored in the v5 docs. The resources and skills we now have available make it possible.

@davisagli +1 for the renaming of just frontend to Volto ui, this would make things much more clear to people.

PR coming soon. It's a little tricky.

[davisagli]

@stevepiercy That roadmap is helpful and I like the direction.

What about something like this as a plan for how to organize the (in some cases hypothetical) How-to Guides:

1. User Guide - How to use Plone through one of its user interfaces. (Primarily for editors, but also web-based admin features like control panels.)
   a. Volto
   b. Classic UI
2. Admin Guide - How to install and operate Plone. Installing, running, configuring, deploying...
3. Developer Guide - How to use Plone as a framework and build things on top of it
4. Contributor Guide - How to participate in our community and make changes to Plone itself

[stevepiercy]

@davisagli I think we need to map things out in greater detail in a Google Doc and not in this pull request. We already have some open issues that cover reorganization, too.

To redirect our focus on this PR, we need to revise the content for public consumption. I'm very anxious to get it done before PloneConf so that all the people who are still using Classic UI would benefit from all the work that the Classic UI folks have done in recent years. As I understand it, many Brazilian government and agency websites run Plone with Classic UI. Hopefully those readers would give back with more Classic UI documentation and contributions. Right now, very few people have a clue about how to contribute to Classic UI packages, and I fear that knowledge will disappear along with those few people.

[davisagli]

@stevepiercy There's not really any line currently between core Plone packages and Classic UI packages. The core Plone packages contain the Classic UI to the extent that they register Zope browser views and templates. So the procedures for contributing are already covered by https://6.docs.plone.org/contributing/core/index.html ... maybe we just have to make that clearer?

[stevepiercy]

@davisagli perhaps "contribute" is not the right word, but "identify" and "develop" Classic UI packages is challenging. We have minimal documentation of how to do some of that, with a big collection of references at the end of the page where the reader has to figure out how they all fit together on their own.

[stevepiercy]

Closing in favor of #1757.