Transfer Plone Deprecation Guide?

[jensens]

Plone Documentation versions affected

• 5.x
• 6.x

Description

I would like to update and transfer the Plone Deprecation Guide to the new docs. But where would it fit?

It needs to be converted to MyST from its source https://github.com/plone/documentation/blob/5.2/develop/styleguide/deprecation.rst using rst-to-myst as described in https://6.docs.plone.org/contributing/documentation/admins.html#importing-external-docs-and-converting-to-myst.

[stevepiercy]

Good question.

We have not yet migrated the Develop docs from the 5.2 branch on plone/documentation.

buildout.coredev docs covers some of the same guidelines and policies.

I think before we take any action, we should take inventory of all the current docs that are policies or guidelines for contributing and developing, then figure out where all the bits will fall into place. I am on board to help determine the structure of these docs. Would you like to take the lead to come up with a plan?

References:

• buildout.coredev docs need to be pulled into Plone 6 Documentation buildout.coredev#840 discusses pulling plone/buildout.coredev docs into Documentation.
• Edit Contributing docs #1278 discusses overhauling Contributing to Plone.

[jensens]

Would you like to take the lead to come up with a plan?

Not now: time limitations. Also, I think first we should finish the current docs. But keep this on hold and come back later.

[stevepiercy]

With the merge of #1486, this issue can now be worked on. @jensens back to you!

[stevepiercy]

Following up on this. This guide is a combination of a Conceptual guide and a How-to guide, and it needs to be split into its two parts. For a definition of these two, see https://diataxis.fr/.

• New page under Conceptual guides
• New page under Developer guide Contribute to Plone 6 core. (Edited 2025-02-13, as we recently added this section, which is more appropriate for things beyond the backend.)

[MrTango]

solved by #1850

[MrTango]

We decided to put it directly in backend, as it is only backend related.

[stevepiercy]

I'm sorry, but we need to split this as originally planned with the recent edit. The concepts and explanation get in the way of how to do things.

[MrTango]

For now please merge it, we can split it later if you insist. But it does not help anybody if we don't have anything in current docs.

[MrTango]

btw this:

Developer guide
This part of the documentation provides information for how to develop in Plone.

was confusing in the old docs and now we do the same, the whole docs are developer docs, if not we split it on the top level into developer, user and so on. If i look at the navigation and start guessing where to find developer topics, i'll stop using the new docs or totally rely on the search, as i do in Plone 5 docs.

We agreed to keep the structure as flat as possible.
If we want the Developer guide menu entry, then we should move all developer topics under it.

[MrTango]

maybe you can explain the structure changes on Discord some time, I'm a bit lost.
For me the following topics should probably be moved under Developer guide:

• Volto UI
• Classic UI
• REST API
• Backend
• Internationalization and Localization
• Contributing to Plone

I'm online on Friday for the Tune up day, so maybe we can talk then.

[davisagli]

@MrTango Here's my understanding of what we aspire to:

1. At the top level, docs should be organized using the Diataxis framework:

• how-to guides (explaining how to do things in a specific way)
• conceptual guides (introducing ideas without explaining how to do things)
• reference
• tutorials

2. Within these areas we aim for a flat structure but:

• We're experimenting with categorizing the how-to guides for 4 audiences that have pretty distinct needs: users (User Guide), admins (Admin Guide), and developers (Developer Guide), and contributors (Contributor Guide). This is my idea and I'm not sure everyone is on board with it yet. The distinction between admin and developer is a bit fuzzy; the others are clearer.
• There is a lot of reorganizing that hasn't happened yet, to achieve this goal.

For many topics, it will make sense to have both a conceptual guide and one or more how-to guides with links between them. For an example, see the docs about Plone distributions:

• conceptual guide: https://6.docs.plone.org/conceptual-guides/distributions.html
• related how-to guides:
  • how to create a distribution: https://6.docs.plone.org/developer-guide/create-a-distribution.html
  • how to upgrade to the built-in distributions in Plone 6.1: https://6.docs.plone.org/backend/upgrading/version-specific-migration/upgrade-to-61.html#distributions
  • how to choose a distribution while adding a site: https://6.docs.plone.org/admin-guide/add-site.html

The deprecation docs do seem like a bit of a grey area for whether they should be split in this way, since even the conceptual information is relevant primarily to developers. But I would argue for still following the Diataxis Framework and splitting it because:

1. the conceptual info can be useful to project managers
2. the conceptual part can cover the principles that are relevant to deprecation across Python code, Volto, and mockup. Then we can have separate how-tos covering the specifics for the different frameworks.

@stevepiercy Let me know if I got something wrong...

[jensens]

The concepts and explanation get in the way of how to do things.

It would going to be a very thin conceptual document.

All from Use-Cases down is a developer-guide, all above (and its not much) is conceptual. Use-Cases could go to conceptual, but well.

Btw.: In Use-cases there is the new use-case (templates) missing.

[stevepiercy]

@davisagli you essentially nailed it.

See also plone/Products.CMFPlone#4097 for why the current Plone 6 Documentation structure that we originally used is terrible for first-timers.

For now please merge it, we can split it later if you insist. But it does not help anybody if we don't have anything in current docs.

@MrTango it's not just splitting the file into conceptual and how-to guides, but putting the how-to part in the correct location as well. It belongs under Developer Guide, not buried under Backend.

It would going to be a very thin conceptual document.

@jensens I don't see that as a problem, but instead as a well-focused concept. We can add cross-references with {ref}`thing` between the conceptual and how-to guides.

Both of these files will likely expand to include Volto, instead of excluding it.

[stevepiercy]

For now please merge it, we can split it later if you insist. But it does not help anybody if we don't have anything in current docs.

@MrTango this comment bothered me, and I would like you to hear me out.

We haven't had this page since I started work on Plone 6 Documentation in January 2022. No one had noticed it was necessary until @jensens created this issue almost 2 years ago.

You forged ahead, which is great and I appreciate, but you ignored my comment about the structure. It seems to me that you dismissed both my direction and the Diátaxis framework as having no value to you. Diátaxis is well-researched, and was adopted by Python, Django, Canonical (Ubuntu), and PyData, to name just a few. We adopted it for Plone Documentation over a year ago, and have been moving toward it incrementally.

Finally, now you want to rush to publish. We know what happens when we publish something with the expectation that things will get done eventually.