Include documentation in plone/documentation

[stevepiercy]

In Discord, @MrTango and I discussed the inclusion of the plone.app.dexterity docs in plone/documentation. The docs would be converted to MyST.

The question arose about how to include the docs, whether to move the documentation as I started for plone/buildout.coredev#840 in plone/documentation#1435 or to use git submodules.

I am in favor of moving the docs to plone/documentation and not using git submodules for the following reasons.

• Easier to set up and maintain
• Easier to cross reference other documentation
• Easier to remove redundancies

The disadvantages include:

• Docs would not live next to code

Please let me know your preference, either with a comment or thumbs up or down emoji. Thank you!

[jensens]

I vote for moving it to documentation.

[MrTango]

I'm for moving it too, otherwise it is not possible to make a well structured main documentation for Plone, if everything is spread.
The argument that the documentation is not close to the code to the code then, is not valid for core add-ons, since we always ship the coredev buildout with the documentation for exactly that reason.

[stevepiercy]

After a week of proposing this move, I think we can green light it.

Next steps:

• Decide where to put the docs in https://6.docs.plone.org/. I think we decided that it should go here https://6.docs.plone.org/backend/content-types.html as a subdirectory instead of a single HTML file.
• Copy docs from plone.app.dexterity to documentation to its root.
• Convert to MyST and clean up. Prepare for plone.app.dexterity docs documentation#1455
• Start moving the cleaned up MyST files into wherever we decided in the first step.
• Update link to docs in https://github.com/plone/plone.app.dexterity/blob/master/CONTRIBUTING.rst
• Update link to docs in https://github.com/plone/plone.app.dexterity/blob/master/README.rst

Thoughts?

[stevepiercy]

As I am cleaning up these docs, I noticed a lot of Unicode specifications, such as title=_(u"Presenter"),. I assume we should drop the u everywhere, now that we do not support Python 2 in Plone 6, correct?

[davisagli]

Correct

…

On Sat, Apr 15, 2023 at 2:27 PM Steve Piercy ***@***.***> wrote: As I am cleaning up these docs, I noticed a lot of Unicode specifications, such as title=_(u"Presenter"),. I assume we should drop the u everywhere, now that we do not support Python 2 in Plone 6, correct? — Reply to this email directly, view it on GitHub <#360 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAL65QEE7YR7UQY45Z5O2LXBMHFDANCNFSM6AAAAAAU5KWVDU> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[stevepiercy]

I have completed the conversion to MyST and its cleanup in plone/documentation#1455.

The plan going forward is to move files from /plone.app.dexterity/ into backend/content-types/. We can do one page at a time. Who wants to lead the charge?

[stevepiercy]

I started migrating docs, providing a roadmap in index.md in plone/documentation#1532. Review appreciated.

[stevepiercy]

While looking at the files inside the directory https://github.com/plone/plone.app.dexterity/tree/master/docs, I realized that most of them are really old, like 7-10 years old, originally authored by @smcmahon, with only minor changes since then. They also appear to be a tutorial, not reference documentation. Tutorials belong in Training, not Documentation. Also I assume that the Mastering Plone 6 Training supersedes this tutorial. @pbauer or @ksuess do you have any insight to the history of this tutorial?

I'm talking about only these 5 files as the tutorial:

• Designing with content types
• Prerequisites
• Schema-driven types
• Model-driven types
• Custom views

Please let me know. Thank you!

[davisagli]

I think this was actually written by Martin Aspeli around the time Dexterity was introduced. (But maybe I'm mixing things up with his book and Steve McMahon was involved here?) I agree, these form a tutorial, not reference docs.

[stevepiercy]

I'll remove them so they don't get migrated. It talks about creating a conference, which is why I thought it might be the origin of parts of Master Plone. If anyone thinks they should be preserved, please let me know.

[stevepiercy]

Sorry everyone, I can't make sense of this documentation structure, and how to best fit it into Plone 6 docs. Tutorial/training, how-to guides, explanation, and reference are all mixed together in illogical groupings.

I would be happy to review this together with someone in real time to come up with a road map. @MrTango and I did that about a year ago, and created the current structure of Plone 6 docs under Backend. I think that needs to be revised, given this content needing a home. I am just not qualified to make guesses for where things should go. HELP!

[davisagli]

@stevepiercy I'm happy to talk this through with you and work on it at the ploneconf sprint -- but not sure I'll have time before then.

[MrTango]

@stevepiercy we will just take out some of it. Mainly the reference part. If there is more useful stuff to be reused for docs we will see. I'm working on the chapters for schemas, fields, widgets and forms. As they all belong together.
Thx for the conversion.