XWiki.org Documentation Reorganization

Development
1

Hi everyone,

I am a Documentation Engineer within the XWiki community, and I’m here to help improve the documentation. My goal is to make it more user-friendly, easier to navigate, and clearer for everyone who uses it. I already have a series of proposals, in collaboration with @vmassol for improvements with more to come in the near future. Community members are welcome to come forward with their own proposals and ideas.

In order to solve current issues with XWiki documentation like difficulty finding the right content for different readers (users, admins, developers), outdated information, and unclear navigation structure- I propose a structured reform based on 4 first steps: applying Diataxis, doc by target audience, track review status and introduce a Documentation XClass.

I will propose additional improvements later on, to make the XWiki documentation more consistent, navigable and user-friendly.

  1. Apply Diataxis

Diataxis is a way of thinking and organizing the documentation into 4 types, each with a distinct purpose:

  • Tutorials- learning-oriented experiences (lesson-like)
  • How-to guides- goal-oriented directions (recipe-like)
  • Reference- information-oriented technical description
  • Explanation- understanding-oriented discussion

Currently, many XWiki documentation pages have a mix of these types, which reduces clarity. We need to make sure that all our docs are of one of the 4 types and that they don’t do more (they should link to other pages for other types). This includes extension docs.

For example:

  • our tutorials are of type tutorial but they often go beyond and add “Reference” and “Explanation” in them
  • our FAQ entries and snippets.xwiki.org pages are actually “howto guides”
  • our Reference documentation often mixes Explanations
  1. Define Target Users

In addition to doc page types (diataxis), also differentiate the pages by target: users, admins, developers.

This distinction should be reflected in the navigation structure, the focus will be on User > Admin > Dev.

  1. Track Review Status

In order to track quality of each doc, each page should include:

  • The last reviewed date (when was the whole page reviewed against the doc best practice guide)
  • The name of the reviewer

These will be managed by properties in the Documentation XClass (see below)

  1. Documentation XClass

It should include the following fields:

  • Type (Tutorial, Howto, Reference, Explanation)
  • Target (User, Admin, Dev)
  • Last Reviewed Date
  • Last Reviewer

This proposal, along with the upcoming ones, supersedes the ideas outlined in this forum post.

2 Likes