In the left navigation panel, readers can already choose the target.
It’s one more level to the location.
It’s harder for the doc writers, because at the moment they need to create it manually.
If you go a level up, the information you find in the Extension landing page is very similar (you can use the LD to filter the target).
Therefore, we consider it brings little value as information. What it does is already covered by the target navigation panel and by the previous page level.
Materializing the type landing page under each topic
Currently, the type landing page (example of type landing page) is a generic page and reused under multiple topics. This changes the breadcrumb (it goes in the XWikiOrg structure), and in the near future it will also make it harder to highlight the page in the navigation, since its URL is different from the topic structure.
Solution:
Make the type landing page specific and place it under the extension name level (instead of the target level) → the structure would look something like ../<extension_name>/<sub-extension_name>/<type>/<doc_page> or ../<extension_name>/<type>/<doc_page>
Pros:
The navigation will be better reflected in the breadcrumb.
Breadcrumb and navigation will be more consistent and easier to understand.
It will be simpler to place documentation pages in the correct location.
The idea is that all type landing pages and extension landing pages could be created automatically when importing an extension on Extensions. (At first, these pages could be empty, containing only an object and a landing page sheet.)
Note: Both proposals are applicable in both XS and Extensions documentation.
My opinion on this is that the navigation tree should be the actual page hierarchy, i.e., that the page navigation tree should be identical to the breadcrumb. Anything else will confuse both documentation readers and writers. If we find that those hierarchies are cumbersome to create/we need to automate their creation, I think we should re-think if we really need them as if they are cumbersome to create and only contain automated content, it seems likely that they also won’t provide any value to documentation readers.
Based on this, +1 for anything that makes the breadcrumbs more similar to the navigation tree.
I’m pretty sure that it’s a bad idea because it’d mean showing too many levels, making the doc impossible to navigate. Just imagine 3 levels more (one for the doc space itself, one for the product being documented - XS, Cristal, etc - and one for the target of the doc - users, devs, admins). We already have 4/5 levels in the nav tree and that’s already the max IMO. Having 7/8 or more level would just be crazy.
Also, the goal of the nav tree is not the same as the breadcrumb (otherwise, why have the 2). The nav tree is just there to present a nav that makes sense in the context where you are. It doesn’t have to be complete.
I think what I wrote wasn’t clear enough, sorry, I didn’t mean that the navigation tree needs to show the full hierarchy from the root of the wiki, what I meant was that the navigation tree should show a complete subtree of the actual page hierarchy, not a completely different hierarchy structure.
Besides the levels Vincent mentioned above (doc space, product etc), in the hierarchy there is one more level that is not displayed in the navigation: the sub-extension landing page. I think that the concept that an extension comes from multiple sub-extensions can be considered advanced and we could hide the landing pages for sub-extensions? This was they will be displayed only for advanced users. WYT about this? Thanks!
I’m still on the fence re subextensions. My main issue with no materializing subextensions is that there are “toplevel” extensions providing several (sub)extensions and they’re not all installed. For example, if you install the Glossary app, you won’t install the LaTeX extension for the Glossary app (you’d need to install it only if you have installed the LaTeX extension) and seeing mentions in the doc about LaTeX in the main Glossary doc would be weird. So one solution would be to materialize sub extensions only when there are several entry points.
Another solution is to always materialize subextensions in the nav tree. For example if you take the “Like” toplevel extensions, it has 3 subextensions: like app, like notif and like api. The main issue is finding the right wording for the sub-tree level, and that’s not always easy.
Hello!
Some updates on this proposal (and on navigation in general): the target level has been removed from the breadcrumb as proposed. In addition, after experimenting Option 1 proposed for the navigation, some drawbacks were discovered and now Option 3 is implemented, but using the {{documentTree}} macro. See the reasoning: XWiki.org Documentation Reorganization (batch 3) - #65 by vmassol. I consider this proposal solved and it’s been implemented. See the results on xwiki.org in the "/Doc" space.
