I've been searching for documentation for contributing to plone in the site and it seems to be missing. Also clicking the Contribute button leads to this: https://docs.plone.org/develop/coredev/docs/None
Further more, I've wanted the Plone Contributor Agreement but then the link provided in the docs (https://docs.plone.org/develop/coredev/docs/contributors_agreement_explained.html) was broken and leads to nowhere.
I hope that I am not raising a taboo issue, but has the possibility to allow comments on docs.plone.org been considered ? At some point of time this was possible on the MS sites and it was pretty useful to get corrections to mistakes or more precise indications, then it seems that they lost interest to police it and it was just stopped and now the doc is often outdated or plain wrong. That's a matter of resources of course.
In the footer of every page in the docs:
About This Documentation:
Contribute
These Docs On GitHub
Although the link to Contribute is broken (I think it's been reported, but I'm too lazy to check in the issue tracker), it is clear that the intent is to allow people to contribute to the documentation. I don't think MS allows people to contribute to their docs in this way. I think it is better way for moderating contributions than allowing comments, except that it lacks immediacy. I also recall the lack of immediacy is another thing being worked on through automation.
As I said, it used to be possible on some MS sites, but not anymore. But it was good while it lasted. Probably too much critical posts. And Github is not for everyone, it's a garden for programmers, not for normal tech people.
Oh alright @svx I mentioned the Plone Contributor Agreement thing specifically here cause, I think new developers will have a hard time contributing for they have no access to the Agreement easily. Plus I couldn't find documentation for newbies contributing, there's no best practices or quick guide for it.
https://docs.plone.org/about/contributing/index.html
And yes the footer links are broken - how frequently are being deployed from git to docs.plone.org ?
@sunew Thank you! I didn't see it the first time I checked and few links I found in the community were broken too so I assumed it wasn't there. My bad. Thanks again!
Managing this stuff over decade(s) is hard. Thank you for alerting us to breakage in the developer entry funnel.
I suppose the expectations of incoming developers have also risen as the world keeps moving on. Time for a documentation sprint?
@svx is the updating process still blocked? What do you thing when we can update the public docs?
I thing there is quite a lot of doc spending.
For example the bobtemplates.plone docs are still outdated and some important things are missing or just wrong if you use the newer version.
How can we help to make that happen?
BTW, Does someone know how to get notification on new releases in general ?
What I mean is, if we would get a notification via a hook or mail or whatever that there are new releases it would help to update the docs faster.
We would need that for releases to pypi and for stuff which is not released to pypi like Ansible roles/playbooks.
If we use a unified GitHub workflow, like with how we name releases on commits we could even write a small scipt which would check certain repos via GitHub API.
@svx I prefer builtin approaches and one of them is to add a "releases.atom" sufix to the repository url, for example, https://github.com/plone/bobtemplates.plone/releases.atom. There's a https://github.com/plone/bobtemplates.plone/tags.atom as well.
If you want other types of notification or automation, I suggest searching google, there are a bunch of services (like https://about.sibbell.com/) that can help you with that.
Yes we definitely need a documentation sprint to bring the docs in theright order and make them accessable.
My main concers currently are:
We will have a sprint after the Plone Tagung in Berlin in March. Does it makes sense for someone that we set the focus on Documentation?
@svx are you comming too?
@jensens, @thet and @gforcada would you join?
We don't need many people, just some who also have a good knowlege of the stack.
Some people who are starters would also be nice, to get some feedback.
We should probably collect some main issues in a milestone, to fix during the sprint.
I've just gotten a hang of how Plone works and I'm quite new to the community. What you pointed out is true, it's a bit of effort getting into Plone with just the docs for any new developer. As a starter, I'd love to give feedback, suggestions and also contribute in any way I can! @MrTango
@MrTango there already various open issues which are tackling lots of the issues, for example restructuring some parts and removing external and out the content under it into the right places.
Also creating a better overview (landing page) which should make it easier.
Etc, etc, etc
But this is way more work and a bit more complicated as it looks on the first glimpse.
It is not done with 'just' moving the content, this goes together with fixing links, the build scripts, etc, etc.
Same goes for removing the READMEs of docs we fetch.
I am not coming to Berlin but @polyester is.
Still I would prefer to organise a own docs sprint for that, at least 3 days (long weekend) for example or even a week, depending on what ppl prefer.
We could do that for example in Amsterdam, asap.
Then maybe find date and go for it. I want to help and I think is really important to fix this. Otherwise there will be no new developer and the community will just shrink. It's important that we find a way, to solve this with more hands than yours to improve the situation as son as possible. A sprint could be good to get some people more involved.
The keypoints are:
This is possible since years, we have docs which are explaining how to do that, including style-guides, reST-guides, issues tagged for new-commer ets.
There is for sure like always room for improvements but we have all this.
BUT, yeah sorry a but 
people have also willing to read and follow these. We have these for a reason :).
This is really depends what you mean by this, this is not always possible because of different content, tone, audience, etc.
For sure it should be consistent in terms of style and according to the audience
As many times already explained, one of the main reasons why the search is not working really perfect and messing up you search is not because of technical reasons.
It has 'simply' to do with the quality of the content, order, usage of header and written word.
You can find that also in my last talk I gave in Barcelona.
As you know we are also including lots of 'external' docs, for example also docs of bobtemplates.plone (not meant personal, no offense )
It would be really great if people who are involved and active in such try to improve these docs. This also would help the all over quality of docs.plone.org a lot !!
Thanks !
