What are you saying with just a link to a separate website? Unless something changed since PloneConf 2016, and unless that PR robot thingie has been removed, even legally insignificant changes to Plone docs require the PCA.
We removed them for a reason, as already said now various times, this is coming back.
The new setup is doing that (testing and pushing to website and docker hub)
The key point here are tests and quality, and that is also why we removed the old 'auto push'. The old setup was with really good intentions and it mage developers happy but is was really bad for the quality of the docs.
You need to have you docs in a certain state of quilty otherwise it make no sense.
Docs are not only for devs, docs are also for 'end user' both of them have different needs.
Even further docs are part of 'marketing', meaning typos, bad grammar, look and feel are important, too.
We have that since years, the setup will change with the nes setup but we have that also with the current one working.
We also have helper tools that people who do not know or who do not want have to deal with virtualenv, buildout, etc. again our audience are not only devs.
Thanks you for you kindly words what you feel about the current search setup !
I am really happy that your solution with duckduckgo is working for you !
Others people told us that even if the search setup is not perfect yet and there is room for improvements they' re are really happy with the agolia implementation.
Sure we could/should improve that !
There is since years a ongoing discussion about that.
AFAIk the last status is,that for small changes you do not need to sign the agreement.
But yeah, this should be more clearly stated in the docs, question for me here is what is small and when is gets big ?
We had that for year, re removed that because:
- it was hardly used
- people confused that with community.plone.org
That is why we moved for now to the Gitter button. The same which is used on plone.org, etc.
Maybe not perfect but for now at least some kind of consistency.
We may try and test other possible solutions inthe future.
Let me qualify that request.
- Automate docs builds on master branch, or whatever branch is the bleeding edge, where it is OK to make mistakes because it is not "stable" or "latest" released docs.
Not having that option inhibits the ability to cut a stable or latest release of docs. If we cannot preview docs in a rendered state, how can we ensure they meet the quality standards you mention?
Where are the instructions for doing this? I've been looking for them for 1.5 years!
Here are my long-standing feature requests for search UI:
- The user should have control over opening links in the same or different window, not the application.
- The search results should remain available and not disappear when one of the results is clicked.
- The search terms should remain available and not disappear when one of the results is clicked.
Algolia is pretty usability- and accessiblity-hostile, and wouldn't pass standards with its current implementation. I'm surprised that anyone is happy with the Algolia implementation, unless they mean for indexing multiple projects and having results available, even though its UI is poor. Perhaps I'm using it wrong, or there is some secret trick to using it productively? I don't use it because it's awful, and use DDG for usability.
Oh that's what this 'Chat' button is for then ! Thanks for the explanation. I clicked on it a few times and what I got is a few Plone developers chatting indeed from time to time about the weather, some Plone users asking for help and getting redirected to community.plone.org (I suggested 2 changes to the doc on community.plone.org and never got any reply so I stopped to do it, it's not a good channel at all for that), even spammers. I never even suspected that it was the preferred method to point at unclear or broken things in the doc; are you guys listening 24/24 on it ?
If yes, could it be explained more clearly on the button, instead of the short but relatively unclear 'Chat' ?
Community is the primary mode of communication I guess, the chat is linked to Gitter and is secondary. @gp54321
@stevepiercy I agree on the search, I don't like them. It confuses me more than the old Sphinx search.
The only thing on the old search, what i didn't like, was that it only showed the title of the pages, which was sometimes not helpfull, because we had many pages with a similar title but in a different context. So a bit more context, would help there. For example a breadcrum of the last 2-3 parent titles. There might be other problems, I#m not aware of. And even though I'm not happy with the current search, I appreciate the work on integrating it. But yes I think we have to spend some energy in that area too.
Regarding the contrebutions to the docs, I thing we changed the rules here, so that for the docs it's not necessary to sign the agreement. @polyester is that already the case or still on the list. That might help a lot.
A "contribute" button should indeed go to github and not to the chat or forum.
If we want something like this, then it's more a "Ask for help" button which points on a page on plone.org which lists the options like the forum or the gitter chat.
To build the docs locally use this: https://github.com/plone/papyrus for now.
There was a pointer in the documentation repo earlier, but it's been removed, because of the upcomming changes. Be awere of that the papyrus repo is doing a lot, because in the old setup we install everything and also render screenshots in the docs. @svx did a lot of work to make this a simpler setup in the future by separating things like the screenshot generation process from the docs it self.
@svx the restructuring sound good and planing and discussing it makes sense.
So folks, lets just improve it.
1 Like
This is not the case, I do not know when you checked the last time docs.plone.org ...
This is not correct anymore, and this is also a reason why we do not advertise papyrus 
With the old papyrus that was the case, but all the stuff is moving and changing.
Also using papyrus is frustrating like hell, usually before we can build a release we spend some time fixing it.
That has todo with different reasons, if you really want to know all of them, I am happy to discuss them over juice or beer
I know it is far from ideal or finished and because of this also sometime frustrating.
Like I said I can't do all at the same time....
The screens are build by jenkins once a week and pushed to a own GitHub repo.
During the build of a release they get injected into the docs.
1 Like
Regarding the button, I'm sorry I didn't check it my self. The last time I checked it was going nowhere 404, but now I think it's fine. The extra chat button is ok. And people get also answers in the chat. Even though the forum is better most of the time, because more people will answer over the time.
Could you explain @stevepiercy how to render it then? Or is it better to wait for some days? I mean at the end it is just RST and Sphinx so rendering shouldn't be a problem. Could be that it's missing the external packages then but should work for testing.
I'm looking forward to see how it will be working soon.
I do not know how many of you actually know Agolia search and how many of took the time to check what you can doing with it.
No offense but by reading your comments I get the impression no one of you actually had a deeper look.
Yes, it is true currently we are using the maybe annoying and not so cool, js snippet.
But this is only the most basic and less time and work/effort included setup.
Actually you can build (and we have planned that already for a long time, but yeah time and ppl factor , you know) super awesome 'static as in non js' pages where you 'easily' can give the results yout look and feel and also chan choose to show breadcrumbs or what ever you like.
The API of Agolia overs you a lot .....
Also like always and I am sorry to bring this up, it is not meant to be personal.
Before we switched to Agolia lots of people where complaining about the results, index and look and feel of the build in sphinx search.
Guess there is no solution to make everyone happy ....
If you look under the hood how Agolia indexes and how Sphinx it does, you will be able to discover that if you have good content you get way better and fine grained results with Agolia.
One other point, we never 'just' switched because we (or I) made the decision because of what I like more.
We asked various times on various conferences and sprints people for their opinion and also for help.
The first plan was to use Solr or ES, lots of peeps wanted to have that and "it was easy to setup,maintain, etc" but no one had time for it or wanted to help
So yeah I am sorry but talking is one thing and doing the work is something else ...
Talk is always cheep ....
Take also please in mind that the 'core docs team' are basically two people (with sometimes the super awesome help of extreme super awesome community members !!!!).
I think you meant @svx. I wish I knew. 
Where is this future plan (and several others, like how to build docs locally) communicated in any written form?
I'm certain that there is at least one person (me) who would love to improve the situation and contribute to these plans, if only I knew where to turn.
The core docs team should provide guidance and direction, and not just say we don't have the time to do the work. We get that, no one has enough time!
For example, put in the GitHub issue tracker: "Create a search results UI using Algolia that satisfies Steve Piercy's persistent gripes about it so he'll STFU", then list those gripes. That's a good start to getting people involved and spreading the workload. Right now, I don't know if the core docs team has this vision: Issues · plone/documentation · GitHub
In fact, when I first listed these issues, only one was addressed without further comment. That tells me that no further work is desired. Is that the intended message? If not, then what is the intended message?
I don't think that the popup gripe can't be worked around at least
I never knew that page existed. How did you discover it? I never saw a link or button for it. There should be something on the template.
Err.. actually I don't remember, it displayed after clicking at random parts of the accursed popup. I swear I never used any secret handshake since I don't know any.
Anyway, the game is up and the secret is revealed now
When all else fails, click madly!
It turns out that this is one of those auto-created pages by Sphinx. It looked familiar, so I double-checked, and it pulls in searchtools.js:
/*
* searchtools.js_t
* ~~~~~~~~~~~~~~~~
*
* Sphinx JavaScript utilities for the full-text search.
*
* :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
I guess the question is whether the core docs team wants anyone outside the core docs team with time available to work on creating a search page that combines the power of Algolia with the UI of a Sphinx page?
with something like that ?
you'll notice the reference to a 'pagination' widget. Should be handy.
If your doc team has access to the Api key, you probably don't need the core team. You could have your private search engine done by anyone mastering Js tools (should be possible to find someone among Plone developers ?) and the common mortals could just use the Sphinx engine that seems to find at least some results.
An after thought:
@stevepiercy indeed you are right some issues are not in the tracker on GitHub, sorry for that !
On the other hand there are more than 100 open issues.
Meaning there is plenty to choose from to contribute.
If you feel like none of the 156 current open issues is something to work on, that is fine too !
You can always ask us (or open a issue) what else you can do. 
The thing is, I am sorry that I repeat myself now, it is better to ask us before you decide yourself to do something what is not communicated with us before hand.
That is not because we do not like people or want them to tell what to do or something else, no it is not about that.
The reason, is that we want to avoid frustration and because not everything is always known to everyone.
On other point I would to bring up is language and communication.
Maybe it really is a culture thing and I 'just' do not understand you or you humor and you do not mean it like I interpret it, but usually I react way better and faster if people do not call stuff I do "rubbish" and bad and not working, and tell me how "they" do it is better.
Maybe it is better,maybe not.
Nothing what I do is perfect and there is always more than one way to solve or do things
This is even is more true if people do not know all reasons, plans, etc.
Again, this is not meant to insult you, maybe it is really a language/culture thing. I yes, I am also not always the best person if it comes to communication.
I did, and only one item from my list was addressed. Closing the issue effectively shut down the conversation on that matter. Well, that is, until now.
So the question still remains: does the core docs team want anyone outside the core docs team with time available to work on creating a search page that combines the power of Algolia with the UI of a Sphinx page? If "yes", then we can discuss details, else I'll drop the matter. I just want to know if you think my list of issues is valid and worth considering.
Sorry to offend. "Rubbish" to me is useless stuff and should be tossed out. It's merely one loudmouth asshole's opinion (mine) of the existing JavaScript search widget. Don't take it personally.
If I took criticism personally, I'd always be offended and depressed, and who wants to live like that? When my work gets criticized, I receive it with open arms and typically ask things like:
- What makes you think that?
- What would improve the situation?
- What can I do to help?
More often than not, it's just someone venting frustration who doesn't want to take any action, but sometimes there is a constructive discussion and we get things done.
OK if people are interested I can to a write up next week about the whole future planning of the docs itself and the test, build and deploy setup.
Just a warning this will be a quite long one and you may personally do not agree with everything or you may think it is 'over engineered' or something.
There are (good) reasons for most of the decisions.
Also you need to be a bit open minded, there may be lots of new stuff for you involved what you may never used.
Last but not least, the new setup is 100% not written from a 'developer only' point of view (think open minded).
It is designed with the intention to meet user and devs !
2 Likes