Looking at some of the struggles newcomers are having, even when they find our docs they don't know about training.plone.org materials, which is a crying shame.
Could we put something in the TOC of docs.plone.org or maybe in each applicable section of docs.plone.org a link to the relevant training materials?
Check the main navigation of both sites, lower left. I added those Dec 1, 2024.
We also have an open issue to improve the entry point for Documentation.
Regarding the struggling newcomers, I need specifics to take action. Please check the relevant issue tracker first, and create a new issue with sufficient details to take action.
Ah, nice to have that cross listing there.
Maybe on each landing page for docs & training we could add a line or paragraph to say something like "you should consult the training documentation for step by step instructions to do various things" (um, wordsmithing that), or vice versa, "you should consult the documentation for supporting information that complements these training materials"
It's generally that they are not finding something they need, but it may not be only that we have things split between training and docs but maybe that something is, in fact, NOT documented because it's too new or hasn't been gotten around to. I don't know if there's a philosophical objection to leaving some stubs in our docs to say "Topic XYZ: yes, we know it's not documented yet, but here's how to ask for help about it." but at least someone looking for information on XYZ would know and wouldn't have to wonder if they had just missed it.
Some finer interleaving of cross links might be nice too, so in, for example
there could be a link to Plone Deployment — Plone Training 2025 documentation
and, even better, at a lower level, some sections of the deployment docs could point to sections of the deployment training.
Some of this will be resolved in Integrating Nuclia Widget by justdaksh · Pull Request #792 · plone/training · GitHub.
I am not opposed to pull requests or issues in GitHub where they are far more likely to be addressed than in the Community Forum.
We could consider adding a paragraph to to the homepage where we describe and link to the trainings, and mention these also work as tutorials. (Add content first navigation).
We could also describe docs..plone.org as the concise ‘reference’ documentation on the homepage. I’m not sure if new users are triggered easily only by words like reference vs tutorial vs training. So a description/hints for when to use which type can be helpful there as well.
When you visit docs on mobile, the tutorials are a click and possibly a scroll away. This is on a large iPhone:
Just trying to get a sense of what people think before I do anything more specific.
Does the GSoC Project of Installation and documentation, also consists this as one point like merging these two pages?
Hi @PredictiveManish – I guess it depends what you mean by merging. The training materials are different from the documentation, even though they sometimes cover the same topics. They’re written differently, because training is meant to be delivered in a class setting (usually at each conference).
If you are asking if this is something that could be done as part of a GSoC project, I would say it’s too large an effort to be done in just a few months, and it would take one or more people with quite in depth knowledge of the topics covered.
Thanks for clarifying. Got your point, for the time being I will do the GSoC requirements and while building complete installation documentation, I hope will get knowledge around the org and then will start working on this if required as of now I am a newcomer so will learn things and then later start implementing.
Thank you for being interested! It’s important to set an achievable scope, especially for a GSoC project, because we want our student to succeed.
