Kim Paulissen: Revamping the plone training and documentation setup for plone 6

published Oct 25, 2021

Talk by Kim Paulissen at the online Plone Conference 2021.

I have been working alongside of the documentation training teams the past months. In this talk I will tell you about the past, present and future of these. Of course, I follow this with a call to contribute!

I am just a messenger. Discussions can get heated between developers when talking about how to document things. Don't shoot the messenger.

https://plone.org should use Plone 6, with default frontend Volto. Rikupekka Oksanen will talk about that tomorrow.

Plone documentation

In the past, the documentation has been written in ReStructuredText, which is a markup language mostly used in the Python community. It was turned into readable web pages using Sphinx, a Python tool.

The main current contents, with target groups:

  • Working with content: for users
  • Adapting and extending Plone: for power users
  • Installing, managing and updating Plone: for sysadmins
  • Developing for Plone: for developers

Now to the present, or what is presently being created. Technology:

  • Markdown as markup language / syntax
  • Docusaurus as React based static site generator

Why this shift?

  • Plone 6 is a headless CMS with Volto (React) as default frontend.
  • Markdown is easier for new (and old) contributors.
  • Easy preview on GitHub and in an IDE.
  • For the people who need to create the new documentation focusing on Volto, they do not need to switch tech stacks.
  • In this way you can focus on the content.

We are not there yet. Various people are working on various branches:

The documentation is still setup to to separated into the two frontend options: Volto and Classic.

All content will be made from scratch. There was an enormous set of docs, some very old, and completely different from what we need now. The old docs will still be kept available.

Daydreaming for the future:

  • up to date documentation that is intuitive for all different parts of our setup
  • improved options for contributing
  • good CI/CD, resulting in changes that get to the live site fast

Plone training

For https://training.plone.org in the past we were using the same technology as docs.plone.org: ReStructuredText and Sphinx.

In the present, we moved to Markdown. Well, to MyST actually. This has most benefits of ReStructuredText added inside Markdown. If you don't know RST, you can simply write Markdown.

It still uses Sphinx, but with Markdown. We use the sphinx-book-theme.

The training team has restructured all the trainings. All were migrated to MyST.

Daydreaming for the future:

  • use the same tech stack for both docs and training
  • integrated following a good documentation system
Keywords
plone ploneconf2021