On discord it is already #training-docs with channel topic
Discussion of Plone trainings and Plone documentation
Issues: Issues · plone/training · GitHub
Sorry, but #training-docs is exclusively for Training documentation and only Training documentation. It's a different beast from Plone Documentation, with its own repo and team.
I'm not sure what is going on with Plone Documentation at the moment. Could we get an update?
@stevepiercy well, missleading topic then, and to be honest, I would like to avoid a channel-flood for every this and that. sharing channels is also sharing ideas. Training and documentation is interconnected anyway. Or at least it should.
There's nothing stopping the sharing of ideas. Just as there are two channels for UI — one for Classic UI and another for Volto, one for each product — there can be two channels for each documentation product, one for Training and one for Plone.
I have not seen the Plone documentation product team share its ideas, not that I haven't asked repeatedly. That doesn't mean it is not happening, I just haven't seen it.
Documentation team is a small overloaded team in need of help and new members with writing docs. Cooperation is a good idea. Communication is a key to get this running. And even Volto and Classic people meet and talk, but both groups a large enough to justify own channels. I also do not think we should split up channels to much. Overall. It is easy to split communication, but much more difficult to join it.
1 Like
All open source teams are overloaded.
The Training docs team already does all that you mention. And more.
To lower the barrier to entry, we greatly simplified many processes and requirements.
- We recognized that some developers prefer one markup syntax over another. We agreed that MyST was exactly what we needed, because it supports Markdown, reStructuredText, and a hybrid of the two, yielding the best of both worlds.
- We changed from manual deployment of docs to automatic deployment through GitHub Actions.
- We restored automatic spell checking and link checking to improve quality and reduce errors.
- We centralized the Glossary,
conf.py, and Makefile to make it easier to create a new Training or update an existing one. - We use a beautiful, well-supported, mobile-first theme, that we customized for our purposes.
- We produced a clear guide for Contributing.
- We renamed the primary branch to
main. - We do not excessively nitpick over details that get in the way of producing useful content. If English is not your first language, who cares? English is hard! Just write something! Someone else will make suggestions and help.
- We set realistic goals and deadlines, and achieve them.
As much as I wish it were, I cannot say the same for the Plone docs team. It is dysfunctional. I know that is impolitic for me to say. I have just pissed someone off or hurt their feelings. Sorry, not sorry. The Plone docs product has stalled for years. If we want that to change, we have to start by being honest about both what is not and what is working well within the project.
The Training docs team did exactly that. We debated, discussed, and worked together through all the disagreements and challenges. I feel honored and fortunate to work with the Training docs team. Their brilliance, talent, professionalism, spirit of collaboration, and commitment is what attracts me to participate.
3 Likes
Wow that went to 110% quickly 
1 Like
How about we just keep the teams separate for now, including separate channels.
We can combine/revisit later if needed
In my opinion training and docs are close together, at least hey should.
With the new docs, i would like to have a solid ground reference, which as also used by references in the training materials. This means communication. And i guess as soon as we get going with the docs now, there is no reason to seperate them anymore. I had the feeling that the training went alone in the past, because the main docs git stuck and individual people could not do much about it, so they went and wrote more trainings to have something.
I like to see the traings and docs growing backtogether a bit more, with a bit less duplication.
I want to make a distinction:
- Plone is a software product under perpetual development.
- PloneConf Trainings is an interactive education product occurring once per year.
Both of these products have their own documentation. These essentially two different products serve different audiences and purposes and have different development and release cycles. One could say, however, there are some similarities and overlap because Plone is the ultimate product.
I had the feeling that the training went alone in the past, because the main docs git stuck
As you noted, one of the reasons that the Trainings Team — as well as the Volto Team — wrote their own docs was because not much was happening with Plone Docs. I think that is about to change, and we might hear more details in the next week and at the Sprint on Saturday, January 15.
I like to see the traings and docs growing backtogether a bit more, with a bit less duplication.
The Training Docs Team identified the need to use Plone Docs as authoritative. See need to synch installation instructions · Issue #254 · plone/training · GitHub and the task under the "Content" section for this issue: Release Plone 6 docs · Issue #1134 · plone/documentation · GitHub
Update relevant Training docs in GitHub - plone/training: Plone Trainings to point to authoritative docs.
Nonetheless, I have a strong opinion that the docs for Training and Plone should remain distinct products. I also have a strong opinion that they should reference one another to maintain connections and to complement each other. I think that importing the Training Docs into the Plone 5 Docs was a mistake, creating duplication, confusion, outdated and conflicting information, and complexity particularly around building them and how to contribute to them. A single set of docs was an admirable goal, but it was impossible to implement well. As separate products, Training Docs and Plone Docs would support each other better than as a single unmaintainable blob.