XWiki.org Documentation Reorganization (batch 2)

Development
,
1

Hi devs,

Second batch of proposal after XWiki.org Documentation Reorganization (batch 1).

This is an important proposal and thus I’m sending it by itself and not bundling it with other smaller proposals that will come after.

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

Proposal 5: Location of Documentation Pages

There are 2 main options:

  • Option 1: Everything on e.x.o
  • Option 2: Everything on the main wiki

Note that having documentation split on several wikis is not good because it prevents having a clean navigation and LD/LTs (as they don’t work cross wikis and even if they worked, the merge would be too complex).

Option 1

  • Create nested pages for the documentation of the extension (one page per target and type)
  • Remove the usage of the Description field and replace the TOC zone with a LD listing children pages
  • Use the XS Standard Flavor as the tip of the documentation (when clicking on the “Documentation” menu link, you land there)
  • Pros:
    • Single place for both extension metadata and extension documentation
  • Cons:
    • Mixes technical content (extension metdata, deps, etc) with documentation, even if the doc pages are under nested pages
    • The user will see that they’re on extensions.xwiki.org and in the header, the logo will be that of XWikiExtensions. It’ll feel weird.
    • The breadcrumb for the doc will have the Extension name

Option 2

  • Move all extension doc from exo to the main wiki.
  • For each extension we will have a page named the same as the exo page (landing page) and under which the various docs for that extension will be.
  • Replace the Description field on exo by a Display macro, to display the content of the extension page on the main wiki
  • Pros:
    • The navigation for the user will be seamless and no odd wiki name/logo will be displayed
  • Cons:
    • Devs will need to import new extensions on exo and document them on the main wiki
    • The breadcrumb for the doc will have the Extension name
    • More reorg work since we’ll need to move more documentation

We also want to separate the doc for XS from the doc for non-bundled-in-XS extensions:

  • The doc for XS should be reached when clicking on the “Documentation” menu entry
  • The doc for non-bundled-in-XS extensions should be reached when going to e.x.o.

In order to achieve this, we propose to:

  • Introduce a new xproperty to the Doc XClass (see previous proposal 4) to mark if a doc page is for XS or for extensions non-bundled in XS (by adding a “bundled in xs” boolean xproperty)
  • By default don’t show non-XS doc in the main wiki
  • By default don’t show XS doc in exo (the LT/LD of extensions should filter out extensions bundled in XS by default)

Visually, the idea is to show if the current doc page concerns xs or a non-bundled-in-XS extension by adding the info on the line of the Likes and Tags, in the form of a pill. In the future, it would be nice to generalize the idea and have a pill with a link to the extension page on exo.

Common

Whatever option is chosen, the general idea is to move all docs under the concerned extensions:

  • When a doc page content concerns several extensions, document it in the parent extension that depends on those extensions.
  • For example the “Edit a Page” how-to has 3 steps: 1) click on the Edit button, 2) Modify the content in the CKEditor UI and 3) Use the action bar to save or cancel. This means this how-to will be located at the level of the XS Flavor extension:
    ├─ XS Flavor Extension (user: howto: edit a page <- at this level as it uses several dependent extensions)
├─ ├─ Flamingo Skin Extension (user: edit buttons + the action bar with save/cancel/etc)
├─ ├─ WYSIWYG Extension (admin: selection of the default wysiwyg editor)
├─ ├─ Realtime WYSIWYG Extension (user: RT feature)
├─ ├─ CKEditor Extension (user: the editor based on CKEditor)

In addition the proposal is to fold all docs that are on commons.xwiki.org and rendering.xwiki.org into the XS documentation and to remove those wikis. They were there initially to try to promote commons/rendering independently of Platform/XS but that didn’t work that well and for the reasons listed above, it’s better for navigation if everything is in the same place.

Conclusion

Our preference goes to option 2 since we need to make it the best for readers even if it’s a bit harder for doc writers.

WDYT?

Thx

2

I like option 2 more too. Option 1 would mean that xwiki.org is only a front for our project and a place to gather our project governance. Right now (and with option 2 similarly), xwiki.org contains both the front for our project, the doc for its default features and our project governance.

One advantage of this is that users looking for doc will also see some navigation to project governance page, which might get them more involved in the community (not only using the doc but also contributing).

AFAIK, a lot of users use the standard flavor. I like the way we show the standard flavor features right now: on https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/ we have them in a secondary list. With option 1., we would emphasize on the fact that those are extensions, which is not really a useful feature for most admins/devs (only useful for very advanced use case and customizations).
With option 1., I’m not sure where we would we move all the base features. I believe a lot of them are transversal to our project and do “work” even without the standard flavor.

I believe option 2. does not make it much harder for doc writers, personally I wouldn’t mind it. The hardest part is to find where to put the extension page in the documentation. That is meaningful information which will make writing good documentation easier (I already know what is said on this topic in the parent page-- I won’t duplicate doc and can expect some understanding of the standard concepts from the reader).

1 Like
3

Yes, I’ll update this proposal later with an example tree. This is what I meant above with:

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.

These are details ATM for me and we can iterate to find the best solution later on. What’s important is to agree on the location of the docs.

Thx

1 Like
4

+1 as well.

Thanks,
Marius

5

I’m +1 for option 2 as well, 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.

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.

6

+1 for option 2, with finer grain details to be defined as pointed out by Michael.

7

+1 for option 2

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.).

8

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:

And:

About:

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

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.

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

9

Globally everyone is ok with option 2 (doc on the main wiki) and with most of the details too.

There’s still an open debate about choosing exactly where you document stuff for a given extension when it is depended upon by another extension and/or when it has dependencies.

In order to progress on this, I propose that I work with @elenicojocariu and @paulinebessoles to try to convert the doc for an extension into what we’d like to have, and verify what works and what doesn’t, and show the results here.

1 Like