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 https://github.com/plone/documentation/issues/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

[tkimnguyen]

Consolidating the docs sounds great to me! It will certainly make contributing much easier. Thanks for nudging/pushing/cajoling 😁

[polyester]

Consolidating is good. The 5.2 docs pull in coredev from the coredev-5.2 branch, so that should be left alone. In the 6 branch we can move to docs

[stevepiercy]

I started work on this in https://github.com/plone/documentation/pull/1435.

The first pass converted .rst to MyST, and added the meta_html headers.

The second pass will have all the obsolete stuff removed and MyST syntax cleaned up.

[stevepiercy]

I have completed both the first and second passes, converting .rst to MyST, adding meta_html headers, cleaning up the MyST syntax and English spelling and grammar, and removing some clearly obsolete stuff.

I also added a lot of TODOs and comments to guide authors and contributors with what I think should be done with the content. I think a couple of pages should be purged, but other contributors may disagree, so I left them in place for further discussion.

All this work was done in https://github.com/plone/documentation/pull/1435 and merged to the branch 6-dev. Now documentarians can pick up from this point, and move one page at a time from /coredev/ and into /docs/.

https://github.com/plone/documentation/tree/6-dev/coredev

The next question is where in /docs/ should we put content from /coredev/? I propose the following:

• Move /coredev/ to /docs/contributing/. All files at this location must apply globally across all of Plone.
• If a file does not apply globally to Plone, then put it in a subdirectory under /docs/contributing.
• Move "Contributing to documentation" from /docs/contributing/ to /docs/contributing/documentation. This is a good example of something that does not apply globally. Documentation has very different requirements and release process than a Python or JavaScript package, although things like the Contributor Agreement and Code of Conduct do apply.

The remaining todos before closing this issue are:

• [ ] Complete migration of coredev docs into Plone 6 Documentation. See https://github.com/plone/documentation/issues/1278.
• [ ] After that is complete, delete docs from the 6.0 branch here. Or maybe delete now?

[fredvd]

Started working on this in the contributing branch of documentation: https://github.com/plone/documentation/tree/contributing

[stevepiercy]

I have been working on this in a separate PR at https://github.com/plone/documentation/pull/1478. The old v5 contributing is not good for v6. Let's discuss this before you invest a lot of time in it.

[stevepiercy]

For anyone watching, this is the final call for review of the PR https://github.com/plone/documentation/pull/1671/ which will close this issue.