XWiki.org Documentation Reorganization (batch 3)

[vmassol]

@CharpentierLucas

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.

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:

@elenicojocariu

Cons:

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

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

@CharpentierLucas

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.

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