buildout.coredev docs need to be pulled into Plone 6 Documentation

[stevepiercy]

The docs for buildout.coredev do not get imported into Plone 6 Documentation at this time. They exist only at https://5.docs.plone.org/develop/coredev/docs/index.html.

First the docs need to be converted to MyST.

After conversion, they need to be thoroughly reviewed and updated for accuracy, especially now that we have Volto as the default Plone 6 fronted. No copy-pasta! If something is not complete, we need to include a todo with a link to an issue to update the content.

See plone/documentation#1278

I will be the champion of this issue, but I need help with the content from experienced Plonistas.

[stevepiercy]

Instead of hosting the docs in a separate repo from plone/documentation, I would suggest that they be moved to plone/documentation permanently and deleted from here. It would be one fewer place to look for docs, and simplify keeping the docs up to date, and give these docs greater exposure and potential to be updated by contributors.

[stevepiercy]

Ping @jensens @polyester @vincentfretin @davisagli @thet @mauritsvanrees @sunew @tkimnguyen @ksuess @spereverde @loechel @esteele @gforcada @svx @ericof as recent contributors to these docs and interested parties for plone/documentation.

Your opinion is important.

[davisagli]

@stevepiercy yeah, I think that's the right approach. Sorry that I haven't made time to work on it yet. I've been busy sorting out some things with our housing and hope to have more time to contribute soon.

[mauritsvanrees]

@stevepiercy Agreed, it makes sense to move this to the main documentation repository. There is no need to keep this here.

Well, if the Plone 5 docs are still being generated, then removing the directory here might break it. Best solution for that would be to let the Plone 5 docs get the contents from the coredev 5.2 branch. @polyester you may know that better.

Steve, maybe you can make a branch of coredev, convert it to Myst, and link the branch in the documentation issue? Then this can be a basis from which someone working on this can copy files as a good start.

Is it best to do one page per PR?

It may make sense to add a link to the Plone 5 docs in the index page, as long as not everything is taken over and properly edited yet.

[stevepiercy]

Well, if the Plone 5 docs are still being generated, then removing the directory here might break it. Best solution for that would be to let the Plone 5 docs get the contents from the coredev 5.2 branch. @polyester you may know that better.

Agreed. I assume Plone 5.2 docs pull in 5.2 from this repo, but @polyester knows for sure.

Until that is determined, I will not remove docs files from this repo.

Steve, maybe you can make a branch of coredev, convert it to Myst, and link the branch in the documentation issue? Then this can be a basis from which someone working on this can copy files as a good start.

There are tools in the plone/documentation repo already, so it is less work to copy the .rst files over toplone/documentation, and start work there. I would put both the original .rst files and converted MyST .md files in a directory called /coredev/ at the root of https://github.com/plone/documentation, as a sibling to the /docs/ directory, in the default branch 6-dev. That's perfectly fine because only files within the /docs/ directory get built by Sphinx and published on the web. As work progresses, contributors can grab content from the converted .md file in /coredev/ from the main branch 6-dev and update its corresponding file in /docs/develop/.

Is it best to do one page per PR?

In this case, yes, along with updating index.md and other files that may link to the
current 5.docs.plone.org. I would be happy with even one section of a page per PR.

It may make sense to add a link to the Plone 5 docs in the index page, as long as not everything is taken over and properly edited yet.

Yes, in fact, that would be part of the first step: create the structure first, then populate it with links to existing docs and a todo with a link to an open issue to add content, until we have time to review content. Here is an example of what I mean.

• https://6.docs.plone.org/backend/vocabularies.html