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.

13

I’m not against it and I even agree with you about the long run. However:

  • I don’t know it at this point so I’ll need to experiment with it. I read the doc but it doesn’t mention how to use it.
  • The main issue I have is that there’s no maintenance for it and it’s not supported by anyone (last release was 29/Jan/24).
  • I think starting with a manual “Related” section is a good first step that we can then improve in the future, and we’ll have the information to transform them into xproperties. I fear that we have already a lot to agree on first.

There are 2 navigations:

  • One for the XS documentation, located on the main wiki
  • Another one, on each extension of e.x.o, to navigate to the doc pages of the extension. For this one, we could use a tree or a LD. We need to refine the proposal a bit I think. I’ll work on that.
14

I’ll repeat the cons mentioned for option 1 and add some more details:

  • As a writer you’ll need to edit the tree to position your new doc page at the right place in the tree since we cannot use any automatic rule for that.
  • We really have lots of topics and they come from various extensions. ATM, I don’t see how having a global tree would be compatible with the “documentation should go in the extensions contributing it”, since extensions are all at the same level (there’s no hierarchy).
    • Basically we’d need to create an XClass that would be used to create a node in a custom Navigation tree, so that the when clicking on an entry you can be redirected to where the doc is (in the extension where it is located), while keeping the navigation tree independent of the underlying structure of pages. It’s doable.
  • Then you need a lot of work to reduce the # of topics and create groupings to avoid having too many topics (let’s say keep them under 20). In an extension world, I think this works when you have a lot of doc manpower and you can refactor pages regularly.

Note: I hadn’t thought about the idea of creating a custom nav tree and this idea of creating the tree based on xobjects added to each doc page. I find it interesting but I fear it would be quite complex to maintain, and for sure people who contribute new pages will fail to properly add them in the right place in the tree for sure, so that would require a lot of oversight.

As you can see above I also wasn’t sure as I wrote the following for option 2:

I’m still unsure but I think I’d like to see it in action before deciding, as option 1 sounds really costly.

Yes they are the same. Not sure what you don’t like about 3 subjects. Right now there are 40 or more… see https://extensions.xwiki.org/xwiki/bin/view/Extension/Application%20Change%20Request%20-%20UI/

In my opinion CR is quite a simple feature to use

haha, that’s funny. It’s a really complex feature (the most complex we have in XWiki and from all extensions that exist ;)). I am discovering this since we have activated it on xwiki.org and started using for doc reorg.

Anyway the doc for it is enough to prove that it’s complex :slight_smile:

15

So a) is option 1 of proposal 7. See my comments to @CharpentierLucas at XWiki.org Documentation Reorganization (batch 3) - #14 by vmassol

Yes definitely, this is what we proposed above, see proposal 6 and especially:

Re b) I don’t think that’s good since there’s no order. For example it’s not because you’re on the “Edit a Page” howto that the next page you’ll want to read is how to “Change the Syntax”. There are as many reading tracks that there are use cases for using XWiki.

First, the idea is to have landing pages at all levels:

├─ Documentation <-- landing page listing all docs for all types and all targets
│  ├─ User Guide <-- landing page listing all docs for all types, for users
|  ├─ ├─ Tutorials <-- landing page listing all tutorials for users

Then re not displaying " how-to/tutorial/reference", the idea is to follow what Diataxis says and it says that it’s usually better for users to follow this order: tutorials > howto > reference > explanations. Since we have landing pages at levels above, I don’t see it as a problem and readers don’t need to understand what type of doc to use if they don’t have an idea.

For example if they’re looking for “user”-level info about “editing a page”, they’d go in Documentation > User Guide and type “edit” in the LD column to find all pages related to editing (or use search).

Yes, I have a proposal for this (not posted yet) which is to create Reading List pages (probably as a Reference type, but not sure) and to highlight them in the landing pages. Remember that on landing pages, we would:

Are you talking about e.x.o or the main wiki? Are you referring to having a double navigation tree: one based on topics (option1 of proposal 7) and one based on extensions?

Note that extensions are very technical and IMO should be hidden from the doc in the main wiki.

Could be interesting indeed. It’s more work for sure (and it will duplicate the content in the page). I think we can delay this implementation as it would always be possible to add it later on. FTM we can try with the page titles displayed in the LD and see if that’s enough.

Note that re it will duplicate the content in the page, there’s a solution that Confluence uses: they have an excerpt macro and you can surround some text with it and then it can be used to display summaries of the page.

Thx

16

There’s no plan to remove these buttons, nor the horizontal menu.

I think there’s a misunderstanding of “to hide”. What is meant is to hide the from the Navigation tree (in the navigation panel).

You said above that you’re for option 2 of proposal 7 but @MichaelHamann is more for option 1.

Yup good point. No mockup planned but we’re working to converting a few pages to show what it would look like. The main visualization point right now is the navigation tree in proposal 7. Once we get an agreement on proposal 7, we’ll start to implement a POC.

Thx

17

That should be free as it’s a LD feature (but we can decide whether we want to use that layout by default or not). I’m not sure it’ll be more user-friendly. Why do you say so? What do you find appealing?

I think we’ll keep it because of Move Cristal from Contrib to XWiki proper - #6 by mflorea (but we need to rewrite it a bit).

Yes I agree we’ll need to decide at some point. It’s too early and right now, CRs have too many bugs to be fully usable. We need to iron that out and get more feedback. Also, we may still want to keep Drafts since there are cases where the doc writer doesn’t know where to put the content or how to split it.

Thx

18

I meant extensions in the sense of non-bundled extensions, not core extensions. I agree that users shouldn’t care about core extensions, but I think users should have an easy way to click through all documentation for, e.g., change request. Also, as I wrote elsewhere, my proposal here is really to have one tree per extension group, so change request would have one tree, not several for the different technical extensions.

But I think it would really help to have some mockups how this would look like or to at least have more examples where, e.g., documentation pages would actually be stored and where it would be listed. In my imagination, those navigation trees would be the actual document trees, not something virtual. But it seems when you proposed this you planned to store documentation pages somewhere completely different and only have virtual navigation trees?

1 Like
19

ok so for non-XS extensions, we indeed need to decide what we do for the navigation. What we have proposed is defined in batch2, in proposal 5:

20

Ahh! Indeed, if that’s what it means “to hide” them, then I don’t have anything against it.

I’m leaning towards option 2 for proposal 7. However, I do agree with some points brought up by Michael, specifically:

  • Having a navigation tree visible on each page. I’m imagining it being on the left side panel.
  • Having previous / next links at the bottom of each page
  • Having child pages displayed somewhere, ideally at the bottom of the page, as to not clutter the main content.

It could be that I’m just misunderstanding what this proposal is trying to achieve. As I said, I find it a bit tricky to visualize :sweat_smile:.

That would be really helpful :pray: :pray: :pray:

Thanks again for working on this! :heart_hands: :heart_hands: :heart_hands: