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