Front-End documentation section organization

Development
,
1

Hello all,

While discussing with @vmassol we identified that the documentation of the Front-End section will include two kinds of documentations:

  • existing UI elements (e.g., pickers) developed since the beginning of XWiki, usually with jQuery, Javascript, and requirejs
  • elements moved from Cristal, or later developed using the same approach, usually with typescript, Vue, ecmascript modules, etc

Some of those elements will likely overlap, and we need a way to distinguish one from the other.
The best differentiation criterion we found is the use of JavaScript for the former and TypeScript for the latter.

Therefore, we propose to use this differentiator in:

  1. the name of the page (e.g., page-picker-api-js)
  2. the title of the pages (e.g., Page Picker API (JavaScript))

The overlapping pages would be located at the same level on the pages hierarchy as siblings.

We can consider three options:

  • Option 1: always make the distinction explicit (i.e., page-picker-js / page-picker-ts)
  • Option 2: only highlight the “typescript” content (i.e., page-picker / page-picker-ts)
  • Option 3: only highlight the “javascript” content (i.e., page-picker-js / page-picker)

I’m +1 for option 3 because I expect TypeScript to be the default in the long term and to gradually replace JavaScript.
Though, this is more work when migrating the existing documentation since more Javascript-related content exists currently.

WDYT?

2

+1 for option 3