The idea is to provide a search entry point that displays results from both the new documentation location and the existing documentation sources (for new documentation searches for pages having the DocumentationClass, for current documentation searches for pages under /Documentation and Extensions wiki).
I propose adding this search box right after the “Current Documentation” cards section (Current Documentation) and before the “FAQ” section (FAQ).
Each documentation page will continue to have its own custom search box for searching within nested pages (e.g., Edit a Page).
For testing purposes, @vmassol helped customize the existing search box, confirming that this approach is technically possible.
Advantages
Users don’t need to decide which documentation section to search from the beginning.
Reduces the number of clicks, pages users need to navigate through
Makes the experience smoother for new users arriving on /Documentation.
Provides a single place to discover all available documentation.
My first feeling is that this should be the default behavior of the xwiki search box at the top right since the purpose of the wiki is a documentation wiki, and returning internal pages by default is not great for users trying to use that search box (which is the right way to search in your wiki).
My second feeling is that it could help to have a search box on the doc home page. It makes it more visible for sure but it could also raise the questions to users about the difference with the main xwiki search box. That’s ok when you land in the doc page since the visible search box clears the doubt but it’s less so if the user doesn’t click on Documentation but clicks on the main search box right from another page (not knowing that there’s a dedicated search for documentation).
In any case, I think it’s globally a good idea. I just have some doubts about what we should do for the main search box.
For me it would be a great addition. I would even put it higher on the page, right after the intro.
Yes, I agree
I understand your concern. I’ve tried to limit my search using the location facet, but the experience of setting this up was not great. However, when I did limit the location to only show the documentation location, the results were great. I did a search for a generic “extensions” string and with the location facet selected, the first result was the page “Creating an Extension”, spot on!
Perhaps one way of dealing with this on the main search is limiting the location facet by default to the location you are right now. You could still unselect it if you want, but at least if I’m on any documentation page, other doc pages would be displayed by default on a given search query.
This approach has a limitation currently, though, as we have two locations for docs, one for the converted ones and another for the docs still to be converted. Would it be possible to converge all of them under a single top-level “Documentation” location, with subpages for the new ones and for legacy?
| Documentation
| |- Documentation for XWiki Standard & Extensions
| | |- …
| |- Documentation for the XWiki Ecosystem
| | |- …
Since the search bar is a separate search box from the existing one, the informational text above it could include a bit more context. The current documentation search boxes on each doc page use the text: “To find specific documentation content, you can either search or filter the table columns below.”
Similarly, for this search box on the home documentation location, we could add something like:
“To find content from both current and new documentation, use the search box below” (or something along those lines).
For the main search bar above the menu bar, we could also update the placeholder text (the input placeholder) that currently says “search…”, to something like: “Search the whole wiki…”. WYT?
Besides “Documentation” (current and new), there is also documentation on exo (Extensions wiki). Because of this, I don’t think it would be possible to group everything under one single “Documentation” location.
We could set the default search config to search inside documentation pages only (documentation/ and /Documentation spaces in the main wiki and Extensions space in the extensions wiki). Users would then have the option to untick the selected wikis/spaces in the facets to widen the search should they need that.
I think globally the idea with the search bar in the home page of the Documentation has been agreed: Eleni, Vincent, Thiago: +1. I agree with Thiago that probably it’s better to place it even higher, right after the intro.
I don’t think it is. The idea of the proposal is to add a search box in the documentation area whereas my proposal is to use the main search.
I don’t agree with this yet. As I said, I feel it’s a bit better to do what I suggested, ie using the main search feature. @tkrieck seems to agree (can you confirm Thiago?), for the reasons I mentioned in my original reply. Don’t you agree @elenicojocariu ?
Sorry, I missed the “default” part of the search config in your reply. I agree that the default global search config could be improved in the way you mentioned; and after the improvement is done we could use it on the documentation home page as well, even if it will be the same in both places.
That’s the part I’m less sure (to duplicate the search feature). My opinion is that XWiki’s default search should be what users use if they want to search in the xwiki documentation but maybe it’s not a problem to also repeat that feature with a dedicated search in the documentation’s home page. @tkrieck WDYT?
I agree on having both, even if a bit redundant. The search on the Doc homepage is highly visible and inviting, while the main XWiki search is convenient and usable when users are on pages other than the Doc homepage.