I recently heard about Google Season of Docs, a program that is similar to Google Summer of Code, but exclusively for documentation. From its home page:
Google Season of Docs provides support for open source projects to improve their documentation and gives professional technical writers an opportunity to gain experience in open source. Together we raise awareness of open source, of docs, and of technical writing.
I would like to take the lead to apply for Google Season of Docs for 2024 on behalf of Plone. It's too late to do anything for this year, and we have a lot of content that needs to be migrated first, so next year would be better.
I was bit confused while following the documentation of documentation. That some parts were for Ubuntu and some for powershell (windows). Instead if the documentation stated different sections for different OS , it would have been easy. And secondly a flowchart would be highly recommended. Like how different things integrate at a point.
I don't know whether I have put clear words or not, if no then please let me know.
More details around deployment. I think there can be more documentation around docker-based deployments. Specifically, something simpler than ansible but more involved that yarn build on the server.
It seems that some projects have done video tutorials in the past:
enhancing some of the docs with video tutorials might be useful, perhaps creating templates and a standard for creating those tutorials.
Deployment is a weak spot in Documentation. Training has Deployment. It's important, but it's one of the most difficult things to get agreement upon because everyone has their own unique process. I would love to see a Deployment Cookbook, where those who deploy Plone sites provide their own recipe to share with others. Maybe from such a collection, we would get a consensus or most popular method that would become "official" documentation. I don't think deployment would be a good GSoD candidate.
Videos are a lower priority to written documentation, primarily due to accessibility, translatability, and searchability. Videos are more time consuming to create and difficult to update, compared to written docs. Additionally GSoD is for the written word.
Keep in mind that the technical writer that we would select through GSoD will most likely not be familiar with Plone, but has the requisite skills for writing technical documentation.
Make the installation clearer by sorting out any confusion between training (5. Installation – Mastering Plone 6 development — Plone Training 2024 documentation) and documentation (Install — Plone Documentation v6.0). Add a special section that clearly explains the differences, so new users know exactly what to do. A bonus would be a flowchart for an even smoother learning experience. From my own experience, this small change can really help curious folks who want things clearer.
Some Trainings have not been updated to use Documentation as the authoritative source for installing Plone, as mentioned in Update relevant Training docs to point to authoritative Plone 6 Docs. There are also multiple use cases of installation—including for creating a Project, deployment, and contributing to Plone—each of which has unique steps. You could submit an issue to discuss the matter in the training repository for the specific training, and suggest a solution that would help reduce confusion. When you do, please add "See https://github.com/plone/documentation/issues/1152" in your pull request.