XWiki.org Documentation Reorganization (batch 3)

Development
1

Hi everyone,

It’s time to dive deeper into the documentation navigation, so here is the third batch of proposals - a continuation of the discussion started in XWiki.org Documentation Reorganization (batch 2).

Note that when I say “We” or “Our” below, I mean @vmassol , @paulinebessoles and myself, as we worked together on this proposal.

Looking forward to your feedback!

Proposal 6: LiveDatas

Use LiveDatas at the following places:

  • At the top level of the documentation provide a big LiveData table listing all doc pages, with filterable columns for type and target (and last reviewed probably too).
  • Use this LD in all landing pages (see below Proposal 8 for landing pages) (user guide, dev guide, admin guide, etc).
  • Also use this LD in all doc pages for listing children pages (Even if XWiki offers the option to view a page’s children as a LiveTable via the ‘More Actions’ → ‘Children’ menu, we felt that this is not sufficient for users. It’s more helpful for them to see the children listed directly on the page in a LiveTable)
    • Implementation note: Use a XSheet bound to the doc XClass to automatically add a section at the end of pages, entitled “Additional Topics”.

Proposal 7: Navigation Tree

The navigation tree in the wiki principal documentation:

Option 1:

├─ Documentation
│  ├─ User Guide
│  ├─ ├─ Page view
│  ├─ ├─ ├─ Tutorials
│  ├─ ├─ ├─ How-to
│  ├─ ├─ ├─ ├─ View a page
│  ├─ ├─ ├─ ├─ View page comments
│  ├─ ├─ ├─ ├─ View page attachments
│  ├─ ├─ ├─ ├─ View page history
│  ├─ ├─ ├─ ├─ View page information
│  ├─ ├─ ├─ References
│  ├─ ├─ ├─ ├─ User actions available on a page
│  ├─ ├─ Page creation
│  ├─ ├─ ├─ Tutorials
│  ├─ ├─ ├─ How-to
│  ├─ ├─ ├─ ├─ Create a page by using the Add page action
│  ├─ ├─ ├─ ├─ Create a page by using a wanted link
│  ├─ ├─ ├─ ├─ Create a page by entering directly the URL of the new page
│  ├─ ├─ ├─ References
│  ├─ ├─ ├─ ├─ ...
│  ├─ ├─ ├─ Explanations
│  ├─ ├─ ├─ ├─ Creating: Simple vs. Advanced
│  ├─ ├─ Page edition
│  ├─ ├─ ├─ How-to
│  ├─ ├─ ├─ ├─ Edit a page using in-place editor
│  ├─ ├─ ├─ ├─ Edit a page using the in-line form editor
│  ├─ ├─ ├─ ├─ Edit a page using section editing
│  ├─ ├─ ├─ ├─ Edit a page using the wiki editor
│  ├─ ├─ ├─ ├─ Edit a page using the class editor
│  ├─ ├─ ├─ ├─ Edit a page using the object editor
│  ├─ ├─ ├─ References
│  ├─ ├─ ├─ ├─ Common edit actions
│  ├─ ├─ ├─ ├─ Page authors
│  ├─ ├─ ├─ Explanations
│  ├─ ├─ ├─ ├─ Section editing limitations (generated heading ids, include/display macros)
│  ├─ ├─ ├─ ├─ What is the Standalone WYSIWYG Editor
│  ├─ ├─ ├─ ├─ Page title vs Page name
│  ├─ ├─ ├─ ├─ Editing: Simple vs. Advanced
│  ├─ ├─ ├─ ├─ Page syntaxes
│  ├─ ├─ ├─ ├─ Edition conflicts
│  ├─ ├─ ├─ ├─ Page force editing
│  ├─ ├─ Page notifications
│  ├─ ├─ Page source
│  ├─ ├─ Page attachments
│  ├─ ├─ Page history
│  ├─ ├─ Page information
│  ├─ ├─ ├─ How-to
│  ├─ ├─ ├─ ├─ Choose a page syntax / convert between syntaxes
│  ├─ ├─ ├─ ├─ Edit page default language
│  ├─ ├─ Page children
│  ├─ ├─ Page printing
│  ├─ ├─ Page export
│  ├─ ├─ Page comments & annotations
│  ├─ ├─ ├─ How-to
│  ├─ ├─ ├─ ├─ Comment a page
│  ├─ ├─ ├─ ├─ Delete a comment
│  ├─ ├─ Page refactoring
│  ├─ ├─ ├─ Tutorials
│  ├─ ├─ ├─ How-to
│  ├─ ├─ ├─ ├─ Delete a page
│  ├─ ├─ ├─ ├─ Restore a page
│  ├─ ├─ ├─ ├─ Copy a page
│  ├─ ├─ ├─ ├─ Move a page
│  ├─ ├─ ├─ ├─ Rename a page
│  ├─ ├─ ├─ Explanations
│  ├─ ├─ ├─ ├─ Limitations of renaming a page
│  ├─ ├─ Page tagging
│  ├─ ├─ ├─ How-to
│  ├─ ├─ ├─ ├─ Create a tag
│  ├─ ├─ ├─ ├─ Delete a tag
│  ├─ ├─ ├─ ├─ Tag cloud
│  ├─ ├─ Page liking
│  ├─ ├─ ├─ How-to
│  ├─ ├─ ├─ ├─ Like a page
│  ├─ Administrator Guide
│  ├─ ├─ Page edition
│  ├─ ├─ ├─ Tutorials
│  ├─ ├─ ├─ ├─ ...
│  ├─ ├─ ├─ How-to
│  ├─ ├─ ├─ ├─ Configure the default editor
│  ├─ ├─ Subject #2
│  ├─ ├─ ├─ ...
│  ├─ ├─ Subject #3
│  ├─ ├─ ├─ ...
│  ├─ Developer Guide
│  ├─ ├─ Application creation
│  ├─ ├─ ├─ Tutorials
│  ├─ ├─ ├─ ├─ Creating a FAQ application
│  ├─ ├─ ├─ How-to
│  ├─ ├─ ├─ ├─ ...
│  ├─ ├─ Subject #2
│  ├─ ├─ ├─ ...
│  ├─ ├─ Subject #3
│  ├─ ├─ ├─ ...

  • Explanations:

    • By target user first, then by subject, then by type (see also Diátaxis in complex hierarchies - Diátaxis)
    • Each tree node with children is a landing page with explanations, some highlighted docs where it makes sense, and a LD with content based on the Documentation XClass and filtered to match the target + type.

  • Pros:

    • Nice navigation

  • Cons:

    • Manual navigation, hard to maintain
    • We have too many subjects (probably hundreds) and it’ll be hard for users to navigate the tree to find a topic (we can only display like 15-20 entries at once in the tree)

Option 2:

├─ Documentation
│  ├─ User Guide
|  ├─ ├─ Tutorials <-- landing page listing all user guide tutorials
│  ├─ ├─ ├─ List 5 tutorials to highlight
│  ├─ ├─ ├─ More...
│  ├─ ├─ How-to
│  ├─ ├─ References
│  ├─ ├─ Explanations
│  ├─ Administrator Guide
|  ├─ ├─ Tutorials
│  ├─ ├─ How-to
│  ├─ ├─ References
│  ├─ ├─ Explanations
│  ├─ ├─ Page edition
│  ├─ Developer Guide
|  ├─ ├─ Tutorials
│  ├─ ├─ How-to
│  ├─ ├─ References
│  ├─ ├─ Explanations

  • Pros:

    • Simple navigation
    • Fixed tree size that can be open fully at all times
    • No maintenance!

  • Cons:

    • Readers will use the LDs to navigate (is it a problem?)

Note: Our preference goes to option 2 (list only some highlights) since there are too many subjects to display at once.

Nav for Extensions

Option 1: A tree

The navigation tree in the change request application page (example):

├─ Subject #1 - CR creation
├─ ├─ Tutorials
├─ ├─ How-to
├─ ├─ ├─ Create a CR
├─ Subject #2 - Manage approvers
├─ Subject #3 - Review CR

Option 2: A LD

Other Navigation Improvements and Cleanup

Also, introduce a left nav panel for the doc home page, for consistency and easiness of nav.

In order to achieve a clean navigation tree/breadcrumb, we need to:

  • To hide:

    • Roadmap archives (no need for users to find that) or maybe better, move that page to the dev wiki
    • Technical active install pages
    • “Macros used on XWiki.org” page
    • Test Reports pages
    • Download, Try, etc
    • Admin tools app
    • “XWiki.org” space
    • Find how to hide the XWiki space

  • To remove:

  • To move:

    • Contribute → to main wiki
    • Surveys pages → under Feedback page
    • Drafts ->under Contributing (create Contributing space and hide it in the nav)

As an upcoming improvement, when Cristal is ready to move to xwiki.org web site, the “Documentation” top menu link will be replaced by a dropdown where both XS and Cristal are listed.
More generally the goal is to have the nav look like what’s listed above.

Proposal 8: Landing Pages

  • Add a “Landing page” type to the Doc XClass (see proposal 4). The rationale is that we could have used a “Reference” type for these pages but we don’t want to display them when the reader is looking for reference pages as we don’t think the reader will expect to find them listed.
  • Have a template for Landing Pages with the following structure:
    • A quick description of what the reader will find under that landing page
    • A short list of pages we want to highlight (e.g. see the “Navigation Tree”- option 2 proposal above), displayed in blocks (similar to Sponsored Extensions on exo for the L&F)
    • A LD listing all doc pages that the landing page represents. Examples:
      • For the top level “Documentation” landing page, display all doc pages having a Doc XClass (for XS only, don’t display non-budled-in-XS extensions by default at least)
      • For the “User Guide” landing page, display all doc pages having a Doc XClass with a target of “user” (for XS only, don’t display non-budled-in-XS extensions by default at least)
      • For the “User Guide/Howto” landing page, display all doc pages having a Doc XClass with a target of “user” and a type of “howto” (for XS only, don’t display non-budled-in-XS extensions by default at least)
      • For each Extension landing page, display all doc pages having a Doc XClass and that are children of that Extension page
2 Likes
2

Thanks for the proposal! While reading it I remembered about the Relation Application (https://extensions.xwiki.org/xwiki/bin/view/Extension/Page%20Relations%20Application/) and I’m wondering if it wouldn’t be interesting to also use that as part of the doc reorganization: I’m pretty sure that we’ll have transverse topics and maybe it could be a good way to visualize those in the pages.
For example, Change Request is a new way of performing editions of pages but you won’t have it as a children of “How to edit a page” probably, but there’s a transverse topic about performing editions. There’s probably plenty of example like this.

+1

I’m not sure to understand the differences between option 1 and 2? In option 2 you’re planning to hide the documents under “Tutorials”, “How-to” etc, or you’re planning to not have them at all at those locations? Or something else?

I’m a bit lost here too: I thought the first proposal was to use LD everywhere?

+1

+1 I’m wondering if on top of that we couldn’t also provide a search section, with a facet allowing to search only in those pages.

3

The way we imagined solving this is by having a “Related” section at the bottom of documentation pages to link to other related doc pages. We discussed this but I don’t think we have a proposal for it. We’ll work on it and consider that app (at first sight seems a bit complex).

Also note that we have an upcoming proposal to use tags on doc pages to indicate topics/features. So for ex you’d have the “editing” tag on both “edit a page” and “edit a page using Change Request” pages. And the idea is to show the tags in the LDs. For ex in the User Guide landing page, the LD would display these tags.

Option 1 is By topic which means listing all topics at the same level under the User Guide, Admin Guide and Dev Guide. And under each topic you have the different doc types. The problem is that there are hundreds if not thousands of topics and it doesn’t scale and that the updating of the nav tree will be manual whenever a new topic is added.

Option 2 is a fixed nav tree by doc types.

The landing page proposal doesn’t mention the extension pages. We’re talking about exo here, not the documentation on the main wiki (if option 2 is chosen for the location of docs, see doc batch 2 proposal (maybe you haven’t read it yet, which is why it’s confusing).

Yes we have an upcoming proposal re search too :slight_smile:

Thx!

4

Honestly I don’t know well the page relation application, but I’ve the feeling that on the long run it might be more interesting than just using tags thanks to its capability to express more semantics on the relation. At first yes it will be more complex to use, but it might allow us to have something more organized.

OK I actually missed the fact that there was “Page view” before “Tutorials” in Option 1, I only saw what was under “Tutorials”. So ok, indeed option 2 seems a better option.

Well I read it, and I just check it again, but I’m still lost sorry :slight_smile: I don’t really understand what this “Nav for Extensions” is about? It’s about chosing what to put at the top of the main entry point of an extension page for navigating among nested pages? So chosing between a tree or a LD to display there? What’s the benefit of using a tree if we’re using LD in all other landing pages in main doc?

5

What about focusing the “Information” docextra tab and using the appropriate extension point to add our info here?
I definitely agree that we need to keep the actual content as the main topic/focus of the doc page and move this info somewhere a bit further.

Another idea I had was to put this info in a panel, but I’m not sure how it’d fit and how we’d avoid displaying this panel on landing pages…

I thought we wouldn’t have that many subjects. IMO keeping a low subject number is an exercise we need to make to improve the documentation (at least we have to in order to use option 1.). What is a subject and what is just an entry under a subject is completely up to interpretation.

On the User Guide itself, could we have some content to provide a comprehensive listing of all the subjects? If we make subjects generic enough, I think most of the new features and new doc would fit under an existing subject and the list of subject would be quite stable.

TLDR: I like this option, but it needs a bit more coordination when picking subjects.

Are those the same subjects as the ones above? I don’t like too much having three different subjects just for CR. In my opinion CR is quite a simple feature to use, I think that one subject would fit better here. I understand this level of specificity in subjects is subjective and will try to fit the level we agree upon once we start implementing. :slight_smile:

That’s a cool project! I didn’t know about it, thanks for sharing :slight_smile: And the “ability to name relations” would definitely be a great improvement. Semantic relations are great to have in a knowledge base.

+1 for proposal 6, preference to implement this in the document extra information tab.
+1 for proposal 7 option 1, need to settle on a level of precision for subjects. Option 2 feels like it’d be overwhelming for new users of the doc, even though it’d be easier to implement for contributors :slight_smile:
+1 for proposal 8, from what I understand, landing pages should not contain anything but references about other documentation pages

Thank you for proposing those improvements!
Lucas C.

6

I’m wondering if relying on Live Data for navigation won’t make it hard for users to navigate the documentation as users won’t be able to naturally navigate through the pages, jumping from one page to the next. It would seem much better to me to have a) a navigation tree that is always visible in the panel that shows the hierarchy where the user currently is and b) previous/next links on each page to get to the previous/next topic. In addition to that, the children of a page could be displayed at the bottom of the page to make it more obvious to users how to jump to a page.

For proposal 7, I’m +1 for option 1, -0 for option 2. Users will want to know how to edit a page, they won’t know if they’re looking for a tutorial, how-to or reference as they don’t know what quality each of these documents has. I’m not even sure I would group by how-to/tutorial/reference below each subject. Also, this would duplicate the information that we already have in the XObject. Instead, as explained above, I would suggest creating a suggested reading order for each subject that gradually increases the knowledge of the reader, with clear indications which parts could be skipped or read for a deep dive into certain aspects of the topic. Instead of having a flat subject list, I could also nicely imagine a nested subject list.

For extensions, I would also suggest a tree in the panel that is always visible.

In principle, +1 for landing pages.

Regarding all those Live Data lists, what about adding a short description to every page that is displayed in the Live Data to give readers an idea what to expect on a page? I know we don’t support this (yet) in Live Data, but it would also be cool to have a custom card layout with, e.g., an icon in the top left corner to indicate the documentation type, then the title and below that a description (and maybe the last updated date).

7

Since we’re splitting the documentation into smaller and more focused pages, I believe the page title alone is usually enough to give readers a clear idea of what to expect. Each page now covers a very specific topic, so adding descriptions might be redundant in many cases. Thanks!

8

I think the “Information” tab is not as easy to discover and might easily be missed by first-time users. By having the related topics listed directly on the page, we help users discover them in context, without needing to switch tabs or look elsewhere. Thanks!

9

+1
Note: with LD we can have a column available but hidden by default. So not using horizontal space when not needed, but easily accessible when needed.

+1
But that shouldn’t prevent generating “summary” pages to list all pages of a kind, since all documentation pages should have enough metadata to query them accurately.

+1

Feel too hidden for me, reader have to go fully down the page, then swich tab.

10

Good point. That’s a nice feature. AFAIU “easily accessible” means that users can configure the LD to make the hidden column visible if they want to see it.

11

Hello! Thanks for working on this!!

Sounds ok to me.

I’m leaning more towards option 2.

For consistency, I’d probbaly also go with a LD.

Looks mostly fine, but I’d keep the “Download”, “Try Now” buttons. I think it would make it easier for users to find these actions quickly.
About the “Donate” button, if that goes away, I think the donation option on the Contributing page should be made more visible, as that’s the page that comes up first when searching “xwiki donate”.

Sounds fine.

This sounds exciting!

I agree with Michael here.

I do have to say that, with this many proposed changes, I find it a bit hard to visualize how XWiki.org is going to look. Are any mockups planned?

12

Hello Eleni, appreciate your work on suggestions and innovative approaches to improving our documents.

Are you planning to set card layout for such LD tables? From my view it will be the more user-friendly layout.

Definetly option 2 - simple navigation for users who don’t use shortcut keyboards very often and don’t use rest search - this will be a big improvement.

Against on removing Forge page - the parent of all pages (that’s where it all came from) and Test space (last one is public)

I’m okay with move and clean of other pages. Only have one suggestion Draft section is used for introducing new section or document in XWiki and since we have CR application it has less value and maybe at some point total remove can be suggested.

no objections here.

Thx,
Nikita P.