XWiki.org Documentation Reorganization (batch 10)

Development
,
1

Hello, everyone!

This topic is about two sub-proposals of the Navigation Tree Proposal that were originally posted in that thread, but since that one was closed and had already become quite large and hard to follow, I’m moving the two sub-proposals here with some updates and resuming the feedback they got so far.

As mentioned in that thread, option 1 of navigation tree was the most preferred option. As a reminder, option 1 is navigation ordered by topic and then by type, for example:

├─ Page (topic)
├─ ├─ How-to (type)
├─ ├─ ├─ Edit a Page (doc page)

Further, there needs to be an agreement on:

How the Type Landing Pages for each Topic are Created

There are two options:

Option 1

Having 4 generic types (howto, explanation, reference, tutorials) that dynamically generate Landing Pages for the corresponding topic. For example: Howtos for users for the Page feature, Explanations for users for the Like feature.

@vmassol did a POC (see https://www.xwiki.org/xwiki/bin/view/XWikiOrg/DocumentationLandingPage/ ).

Pros:

  • Avoids creating so many landing pages (there will be 4 pages per topic and there are hundreds of topics).

Cons:

  • Readers lose where they are in the navigation tree. → This can be solved (see Vincent’s comment).
  • Not a nice breadcrumb (check an example).

Option 2

Creating dedicated Landing Pages directly under each topic.

Pros:

  • Nice navigation and breadcrumb.

Cons:

  • Many landing pages.
  • Readers can already filter from the LD on the topic Landing Page the type, for example check the LD on this Landing Page of a topic.

So far, the summary of this proposal is:

  • Pauline is more for option 2
  • Simon is more for option 1

Note: There will most likely be a Sheet configured for the Landing Page, so contributors will only need to create a Landing Page from the template.

The other sub-proposal that needs an agreement is:

Order of Pages in the Navigation Tree

Choosing the order can be quite subjective, but the following criteria should be considered:

  • List pages from most useful to less useful, considering how often a feature is used.
  • Use the Common Criteria to help decide.
    • For example, both “Hide a Page” and “Change the Syntax” belong under “Page”. “Hide a Page” is listed before “Change the Syntax” because hiding a page is used more frequently, while choosing a syntax usually happens only when creating a page.
    • Another example: the standalone WYSIWYG editor, also under “Page”, has a very specific use case, so it should be listed lower in the tree.

Note 1: This order is proposed with the understanding that we’ll probably never get a “perfect” structure everyone agrees on. That’s why having common criteria is important, so contributors have a clear reference and the navigation can grow in a consistent way.

Note 2: This order applies to the navigation tree of the XWiki Standard. For non-bundled Extensions, the plan is to list the features alphabetically.

The status for this is:

  • Pauline: +1 with the mention that when in doubt where to place the page in the nav tree, ask on the xwiki chat.
  • Lucas: agrees with the proposal only if we decide to display a limited number of doc pages per topic, with an option to “show more” to expand the tree; otherwise he prefers alphabetical order.
  • Simon prefers also alphabetical order.

Thanks a lot to everyone who has shared feedback so far and participated in the discussion! Feedback from anyone who hasn’t had a chance to share their thoughts yet is very welcomed!

Thanks!

XWiki.org Documentation Reorganization (batch 3)
2

Re alphabetical order, I’m strongly -1 as there’s no way that it can match what the reader expects. It also goes against the reading order that Michael wanted to have. For ex, seeing “Active Installs” first and not showing how to edit pages before makes little or no sense. There’s no way to avoid manual selection of page order to read. Even if it’s tedious to maintain.

We could do alphabetical order on the not-bundled-in-xs extension documentation part (but even there I’d order by active installs for ex which seems better than alphabetical order). But the topic here is the XS documentation part, and there alphabetical order makes no sense. If you’re not convinced check the website doc for any software and you’ll never see docs by alphabetical order.

TBH I don’t even understand how alphabetical order could be proposed without any argument as to why it’s good for readers. The goal of the doc of xwiki.org is not for us developers (the proponents of alphabetical order say that it’s simpler for devs ;)), but for xwiki.org users.

What Michael mentioned about Pinned Pages is more interesting but it wouldn’t work either since we’d need to pin 100% of the XS pages.

Now, re the navigation order, we now have a doc team with Eleni being the lead. So it could work like this:

  • Add a CR for positioning the new doc and Eleni can review it and be the “owner”/“responsible person” of the navigation
  • If you’re sure of yourself then directly edit the navigation (Eleni will watch the page changes anyway)

And of course, use the critera we will have listed in the doc guide to propose a location (in the CR or directly).

Thanks

3

Hi!

Some updates:

Thanks!