Release Plone 6 docs

[stevepiercy]

This is a placeholder issue for the imminent release of Plone 6 docs as being tracked in the GitHub Project Board Plone 6.0 - tasks to final.

Documentation project board: https://github.com/orgs/plone/projects/12/

View current state of Plone 6 documentation: https://6.docs.plone.org/

Organization

Discord server

https://discord.gg/NES2f6dQ
Channel: #training-docs

List the principals and their roles for this issue.

GitHub username	Roles
@ericof	Automation
@ksuess
@pbauer	Training
@polyester
@sneridagh	Volto docs
@spereverde	general structuring/writing docs
@stevepiercy	Lead cat herder
@svx
@tkimnguyen	happy to help, but no specific idea where to start yet
@MrTango	Classic UI / Backend
@flipmcf	Gopher
Insert Your Name Here

Features and Automation

• Automate testing of docs on each pull request
• Automate deployment to 6.dev-docs.plone.org #1146
• Investigate Netlify as possible deployment infrastructure #1154
• Spell checking
• Link checking
• Use redirects to avoid link rot with sphinx-reredirects #1149
• Makefile
• Filter search results by primary section, other?
• Search results should show breadcrumbs #1156
• Page titles show chapter title - sub-chapter title - Plone Documentation
• Improve SEO with html_meta directive. #1147
• TOC is sticky (always displays while scrolling), and may be collapsed or hidden
• Code can be copied with a click
• Glossary
• Automatically generated index

Which tech stack?

• Sphinx and MyST: Supports reStructuredText and a superset of CommonMark markdown. Used by Training docs.
• Current: hell no.
• Coster: seems to have disappeared.
• Docusaurus: new to developers, lacks features that Sphinx provides OOTB.
• Determined that we shall use MyST and Sphinx for our tech stack.

Branches

• Create 6-dev. This is the feature branch where development for Plone 6 Docs occurs.
• 6 is the main release branch for Plone 6 Docs.
• Merge backend-6 into 6-dev.
• Merge classic-ui into 6-dev.
• Delete volto-frontend as there is nothing of value in it.
• Determine how to integrate https://docs.voltocms.com/ #1148

Structure

• See Plone 6: [dev] Backend / Classic UI  #1137
• Create a table of contents for each primary item, keeping it as shallow as possible.

Theme

• Select and use a mobile friendly theme, preferably one that unifies Plone, Training, and Volto docs, giving users a coherent experience.
• Customize the theme to align with Plone branding #1150

Content

• Update content for how to install, maintain, and deploy Plone 6 #1151
• Create instructions for how to:
  • write new docs as an Author or Developer
  • contribute to existing docs as a Contributor
• Update relevant Training docs to point to authoritative Plone 6 Docs #1152
• Create a clear guide for Contributing to Documentation #1153

See plone/training#254 (comment)

[ksuess]

Summary of the sprint meeting 15.02.2022 14 CET
Present: @polyester @sneridagh @rioksane and plone.org sprint participants.

Paul summed it up already in Discord:

• use the same tech stack as training
• use only one branch, for both classic and volto
• use markdown as the language
• bring them online, automated, under something like https://6-dev.docs.plone.org/
• start working, refine later.

My opinion

• on branches: One branch to have one point to continue with contributing. Be clear to the plurality of potential contiributors where to drop changes, additons, continue writing. I think this is what attracts more contributors.

I can setup a merged branch "6-dev" with all new already written docs for Plone 6. [New merged working branch set up : https://github.com/plone/documentation/tree/6-dev]
@ericof Could you set up a subdomain 6-dev.docs.plone.org and the deployment of the branch "6-dev".
@stevepiercy It's a pitty that we set up the meeting on time that's not yours. Do you want to continue with setting up Sphinx, theme, Makefile, checkers, etc. on branch "6-dev"?
@polyester wants to enhance the set up with guide lines and editor configuration for a political correct language and more.

[ksuess]

Project for involved issues: https://github.com/orgs/plone/projects/12/

[MrTango]

Regarding the structure, we started here with defining how we would see backend and classic-ui being structured, so that we have backend which is for headless and classicc-ui and the classic-ui topics. Volto-ui will be the 3. category and probably pointing to backend topics.
#1137

[stevepiercy]

I have locked conversation on this issue because I created separate issues for each of the remaining tasks that is not in PR #1141. I will keep it open as a reference.