Feedback on the New Documentation

[elenicojocariu]

Hello XWiki users!

Since May 2025, we have been working on improving both the documentation of XWiki and the guidelines that support it. The “new documentation” refers to the content now located under “/documentation”, where we have started converting and reorganizing older pages previously found under “/Documentation” or on “Extensions Wiki”.

Our goal with the new approach is:

• to make it easier to find and navigate content,
• easier to read and understand,
• more up to date overall.

We’d now like to gather your feedback on this new direction.

What do you think about the new documentation compared to the old one?
(Feel free to comment on anything related to navigation, structure, content, or contributor guidelines.)

Thanks!

[gabrielc]

Helloo!!

The new documentation space looks great. It feels cleaner and the documentation pages themselves are bite-sized, so it’s easier to get through them or to quickly understand how to do something.

Still, something feels a little off when searching for content. I feel like it’s still hard to find docs pages that already exist.

For example, let’s say I’m a person that has never used XWiki before, and I’m evaluating weather I should give it a try. I really care about page versioning capabilities. I somehow get to the new doc space, it looks great. I browse a bit, the pages seem short and focused. Amazing. Now, let’s see if XWiki has page versioning capabilities. I type “versioning” in the “What are you looking for?” search box… “(No entries)“.

I know that the correct thing to type in the search box would have been “history”, but a new user or someone that’s not even a user yet, may not know that. I think it’s really tricky to tackle this issue, but I think it is necessary. The usefulness of the new doc space goes down if people can’t find what they’re looking for.

To summarize:

• How does it look compared to before? - Better!
• How is the content compared to before? - Up to date, cleaner!
• How is the search compared to before? - Ermm.. the same.

Thank you for working on this!!

[vmassol]

@gabrielc

For example, let’s say I’m a person that has never used XWiki before, and I’m evaluating weather I should give it a try. I really care about page versioning capabilities. I somehow get to the new doc space, it looks great. I browse a bit, the pages seem short and focused. Amazing. Now, let’s see if XWiki has page versioning capabilities. I type “versioning” in the “What are you looking for?” search box… “(No entries)“.

I agree. That’s because the LD filtering is not a search.

What we discussed but haven’t implemented yet (I think we forgot a bit) is the Search. See https://design.xwiki.org/xwiki/bin/view/Proposal/Diataxisforxwikiorg#HOther which says “Proposal for Search”.

There are 2 ideas (but we should discuss them in a dedicated thread proposal):

• Use the wiki search and restrict search to the documentation space on the main wiki + a few other spaces (like content pages linked from the horizontal menu) + snippets + design wiki + etc.
• Add a dedicated search box on the doc home page (probably the best), restricted to the doc space.

@elenicojocariu let’s work on that search proposal.

BTW when I start typing “v”, “e”, “r”, “s”, “i”, etc I get the following:

@gabrielc can you explain what you did precisely? On what page you typed “versioning”?

Thx

[gabrielc]

@vmassol

What we discussed but haven’t implemented yet (I think we forgot a bit) is the Search. See https://design.xwiki.org/xwiki/bin/view/Proposal/Diataxisforxwikiorg#HOther which says “Proposal for Search”.

Ohhh! I didn’t know about that. That’s quite nice.

@vmassol

There are 2 ideas (but we should discuss them in a dedicated thread proposal):

• Use the wiki search and restrict search to the documentation space on the main wiki + a few other spaces (like content pages linked from the horizontal menu) + snippets + design wiki + etc.
• Add a dedicated search box on the doc home page (probably the best), restricted to the doc space.

I prefer the 2nd option with the dedicated search box.

@vmassol

@gabrielc can you explain what you did precisely? On what page you typed “versioning”?

Indeed, typing anything up to the word “version” brings up the correct pages. I typed “versioning” quickly, before the LD had time to update.

[elenicojocariu]

Hello!

Thanks for the feedback!

I think your comment reflects indeed the need of having a search inside the doc space. The search in the LD on the “/documentation” page currently only looks in page titles, while the main search on xwiki.org searches in the entire wiki. I agree with Vincent that the best approach would be to have a separate search dedicated to the documentation.

Also, I think your comment could relate to tags too. I’m not sure if it’s a good idea yet, but maybe we could include a “tags” section in the doc search? (The idea of using tags in the documentation has come up a few times, but no proposal exists so far.)

For example, if you search for “versioning” in the doc search bar, a “search page” (similar to this Search page) could open showing all pages and tags related to the term searched. The tag area could be similar to Extensions Wiki-browser extensions.

Note that doc pages from Exo already have tags set, and now that we’re moving the documentation to the main wiki, it would be a loss to make users search tags on the Extensions wiki instead of the main wiki.

WYT? Thanks! If the idea is is liked and feasible, I will include it in the proposal for the dedicated search in the doc space.

[gabrielc]

@elenicojocariu

Also, I think your comment could relate to tags too. I’m not sure if it’s a good idea yet, but maybe we could include a “tags” section in the doc search? (The idea of using tags in the documentation has come up a few times, but no proposal exists so far.)

I’m +1 for searching through tags as well. If feasible, it may be helpful in some cases.

[vmassol]

@elenicojocariu

The search in the LD on the “/documentation” page currently only looks in page titles, while the main search on xwiki.org searches in the entire wiki.

It’s not a search… it’s a filter. But I can see how users may think it’s a search. But I think if we put a search box above on the doc home page, it’ll be clear. We could also add an explanation sentence.

@elenicojocariu

Also, I think your comment could relate to tags too. I’m not sure if it’s a good idea yet, but maybe we could include a “tags” section in the doc search? (The idea of using tags in the documentation has come up a few times, but no proposal exists so far.)

I really don’t like tags because you have exactly the same problem as mentioned by Gabriel and it’s quickly a mess:

• Example: We tag with version, it’s not versioning…
• Someone else tag with versioning or history, or revision or… and suddenly you have a mess and can’t see all the pages on a given topic.

@elenicojocariu

For example, if you search for “versioning” in the doc search bar, a “search page” (similar to this Search page) could open showing all pages and tags related to the term searched. The tag area could be similar to Extensions Wiki-browser extensions.

And how do you implement that?

Re tags, we also need to decide if we’re going to use them or not, see https://design.xwiki.org/xwiki/bin/view/Proposal/Diataxisforxwikiorg#HOther. Personally I’m relatively against unless we add some feature inside XWiki to restrict the possible tag values. Also we’d need to wait for LD to support tag cloud before we could use them…

[vmassol]

@vmassol

What we discussed but haven’t implemented yet (I think we forgot a bit) is the Search. See https://design.xwiki.org/xwiki/bin/view/Proposal/Diataxisforxwikiorg#HOther which says “Proposal for Search”.

If you want to see what you’d get when searching for “versioning”:

https://www.xwiki.org/xwiki/bin/view/Main/Search?r=1&f_wiki=xwiki&text=versioning&l_space_facet=10&f_type=DOCUMENT&f_locale=en&f_locale=&f_space_facet=0%2Fdocumentation.

Looks pretty good to me.

[vmassol]

@vmassol

It’s not a search… it’s a filter. But I can see how users may think it’s a search. But I think if we put a search box above on the doc home page, it’ll be clear. We could also add an explanation sentence.

@gabrielc done. All landing pages now have a search box. See for example https://www.xwiki.org/xwiki/bin/view/documentation/xs/

[gabrielc]

Thank you for working on this Vincent! It looks great IMO and seems to find a lot more stuff compared to the filter.

One small mention is that some users may be confused by having both the search and the filter on the page, but at the same time I think the filter is still necessary (especially for the Type and Target). So I’m not currently sure how this could be improved.

[vmassol]

@gabrielc

One small mention is that some users may be confused by having both the search and the filter on the page, but at the same time I think the filter is still necessary (especially for the Type and Target). So I’m not currently sure how this could be improved.

This is why I added the text: To find specific documentation content, you can either search or filter the table columns below.. If you think it’s still confusing, we could tune the sentence.