Apply Diataxis

All documentation pages must follow the Diataxis methodology, which is a way of organizing the documentation.

In Diataxis, all pages are of one of 4 types:

• Tutorials - learning-oriented experiences
• How-to guides - goal-oriented directions
• Reference - information-oriented technical description
• Explanation - understanding-oriented discussion

In addition, pages are segmented into three target audiences to make it easier for readers to find relevant content based on their usage profile:

• User
• Administrator
• Developer

In order to apply Diataxis, split pages by type, and target. This is simply done by creating a documentation page at the right location and completing correctly the fields of the documentation page structure.

Set the corresponding TechnicalId to the Page

When creating a documentation page, you must also fill in the "Technical ID" field within the documentation page structure of XWiki.org of a documentation page, if it has a "Technical ID" associated. In cases where no "technical ID" is linked (for example installation pages), you do not need to fill in this field. This is done so each documentation page on the main wiki is linked to the extension it comes from or as a NPM package. 

To correctly fill in the Extension ID:

1. Go to the extension page that provides the feature documented in your page.
2. Locate the Id metadata, which is stored in the xobject of type ExtensionCode Class.
3. Access and copy the ID using the Object Editor, as illustrated below:

   

   • If the extension page does not exist on Extensions, it needs to be imported. Make sure to handle the extension page properly and add the "Documentation" button as described.
   • If the page exists but the id field is not filled in, it needs to be completed.
     • The Extension id follows the format <groupId>:<artifactId>, where the artifactId corresponds to the extension name (e.g., org.xwiki.platform:xwiki-platform-icon-api).

To correctly fill in the NPM Package:

1. Go to npmjs.com.
2. Search for the XWiki package you are looking for.

In xwiki.org documentation, we reflect Diataxis also in the Documentation Style.