XWiki.org Documentation Reorganization (batch 2)

[vmassol]

@MichaelHamann

but I’m not sure regarding the content of the extension page. I think it would be nice if the extension page would provide an overview which features the extension provides, aimed at admins who want to understand if they should install the extension. So basically, the difference would be that the extension’s page is aimed at admins who don’t have the extension installed (or want to understand which features they’ll lose by uninstalling the extension) while the regular documentation would aim at users, admins and developers who have the extension installed.

I think there’s a misunderstanding. The goal is to keep the doc displayed on the extension page (on exo).

This is what I meant with:

@vmassol

• Replace the Description field on exo by a Display macro, to display the content of the extension page on the main wiki

And:

@vmassol

Also, one idea I have is to use a {{display}} macro automatically on the exo page for each extension with the reference filled automatically (and pointing to the right page on the main wiki). Either that or a link to the documentation (which would appear as a wanted link - nicer for devs, but slightly less nice for readers who need one more click to read the doc.

About:

@MichaelHamann

Further, I’m not convinced we should group documentation by individual extensions. Instead, I would be in favor of a) not grouping anything for bundled extensions and b) organizing documentation by extension group where that makes sense. Each page could have metadata (XObjects) that provides information which individual extension(s) provide the described functionality. For example, I would suggest having one documentation root for the AI integration. There we could then have user, admin and developer pages in different subpages that use one or several of the extensions that are provided by the AI integration.

I think this is what I meant too when I said:

@vmassol

When a doc page content concerns several extensions, document it in the parent extension that depends on those extensions.

I gave the example of the “Edit a Page” howto above and where it would be documented among the various extensions contributing to it. In general, the howtos are going to surface at the top level since they depend on several extensions to work, but you can have cases where the doc page only concerns an extension, and not a parent extension depending on it.

@tmortagne

I agree that for a lot of multi extensions projects, the documentation would be a lot clearer if the user/admin/developer separation is made at project level instead of for each extension (some extensions won’t even be mentioned in the user area, etc.).

Several remarks about this:

1. This separation between user/dev/admin is even made at a higher level, see the navigation tree proposal 7 on XWiki.org Documentation Reorganization (batch 3)
2. At the extension level on exo, my idea so far is to have a landing page (see proposal 8 at XWiki.org Documentation Reorganization (batch 3)), ie a LD with all the doc pages listed in it (and categorized using the doc xclass), with some possible highlights of the important docs (described in proposal 8).
3. The problem we have with extensions is that they’re not hierarchical; they’re all at the same level and we cannot have a tree since it wouldn’t be acyclical. Thus the doc pages for extension you depend on won’t be listed in the LD mentioned in remark 2). One way to solve this (and that I have not proposed yet) is to introduce the concept of “Related Pages” for doc pages and landing pages. It would be a static list of doc pages that are related but not children.
4. The concept of “project level” is not really defined for XS, or it means the top level XS flavor (which will be the home of the doc). BTW this is where I suggest to document the “Edit a Page” howto in the example above. Said differently there are “project level” at all levels and I don’t think we should reason with that concept. I prefer to reason with the concept of dependent extensions.
5. If you take existing examples of contrib extensions having a project level, such as the LaTeX extension, it makes a lot of sense to me to not document everything at the top level because several features only make sense if you install the extension (and you don’t install them by default if you install the entry point extension for example).

thx