Documentation Guide

General Remarks

This document is meant to provide best practices on how the XWiki.org documentation should be written and maintained.

On XWiki.org documentation efforts usually go towards:

• Fixing bugs.
• Improving existing documentation.
• Keeping pages up to date with the latest changes in XWiki.
• Creating new documentation for new features, applications, procedures, etc.
• Refactoring documentation pages to the new location.

As of September 2025, documentation is being refactored: we are moving content to the Documentation for the XWiki Platform location and applying the Diataxis framework. Currently, documentation can be found in three places:

• Documentation for the XWiki Platform (the "/Doc" page): the new location, where several pages have already been converted.
• Documentation (the "/Documentation" page): old location from the main wiki, where unconverted documentation pages are still located.
• Extensions (the Extension sub-wiki) : where unconverted extension documentation pages are still located.

During this migration, sections or whole pages content from both "/Documentation" and Extension sub-wiki have already been moved to "/Doc". In their original locations, these sections have been replaced with links pointing to the newly converted pages. Over time, both the main documentation and the extensions will be fully moved under "/Doc".

Requirements

The following things are important when contributing to documentation:

• Your will
• Having basic English skills, as all documentation should be written in English (since you are reading this guide, your skills are more than enough).
• Testing every feature that you want to document in a wiki environment running an LTS version or beyond.
• Being registered as an XWki.org user (use the "Register" link on the top right).
• Understanding the concept of Diataxis.
• Following this guide.

Minor Changes

Sometimes you will encounter small issues in the documentation. Examples of minor changes include:

• Grammar or spelling errors
• Typing errors
• Broken links
• Revising or slightly rephrasing texts for clarity
• Other small, low-impact fixes that don't affect the overall structure or meaning of the page

Such bugs should be fixed directly on the page, without creating a Change Request. You don't need approval, just fix them

When making minor edits, please remember to:

• Mark the changes as "minor". This way you don't send notifications to people following that page (by IRC, mail or RSS) each time you make a minor addition.
• Write a short summary describing the fix (e.g., "fixed typo", "fix broken link" etc.).
• It's preferable to click "Preview" when editing a page with the Wiki editor to view your changes before you save the document. This prevents saving incorrect content and sending "spam" notifications to people who explicitly configured their settings to receive minor ones.

Major Changes

Major changes are edits that impact the structure, organization or content of the documentation. Examples include:

• Creating new documentation (documenting a new feature or adding content to an existing feature).
• Refactoring a documentation page to follow the new organizational rules and the new style rules of the Documentation Guide.
• Restructuring navigation, moving content between locations, reorganizing sections.
• Updating many pages at once.

For these cases, you must follow the new rules in this Documentation Guide. It is recommended that major edits you are unsure of are saved in a Change Request, so that they can be properly reviewed and validated before being published.

Start contributing

After you read and understand how you should create and modify documentation you can start contributing yourself. Not sure what to work on? 

• Here's a list of pending to do's. 
• You may also check the List of all violations and fix them (if any).