Use the `ReviewClass` for Documentation Quality and Validity

Development
,
2

Thx @elenicojocariu

I think we can improve this a bit more. We need to better address the need which was to make sure that readers of xwiki.org don’t find incomplete or wrong information, especially in the period when we’re migrating pages.

Right now the official doc is in 2 places:

  • In the old docs for pages not moved yet.
  • In the new doc for pages already moved (with links from the old docs)

Thus when some new doc content is being authored the readers need to know if it’s in progress (ie incomplete or inaccurate) or finished (they can rely on it).

What I had started discussing with @elenicojocariu was this process:

  1. Whenever you start writing some new doc, you add a warning box with a WIP message. This message should include a link to the original doc if it’s being moved. If it’s some new doc, then just WIP should be enough.
    1.1 If migrating some old doc content, add a warning box inside the old doc content to explain that and DO NOT remove the old content yet, even if it’s been fully moved (i.e. it’ll now be in 2 places).
  2. Ask for a review. Note that there should be single type of review and not two as proposed above since there’s no concept of review type in the XClass/XObjects and I don’t think we need one. A review is always a review of Quality, i.e. are doc guide being followed properly + is the content accurate and/or missing something. Discussions happen on #xwiki or in a forum post.
  3. When the reviewer says it’s ok, and only then:
    3.1. Remove the old content (if it was content being moved) + the WIP warning
    3.2. Remove the warning in the new content page
    3.3. Set the reviewer metadata

WDYT?

Notes:

  • Regarding annotations, I’m -1 ATM since we said we don’t want comments on xwiki.org as it’s proved to be a pain. Or we need a way to turn them on doc by doc temporarily and once the doc has been reviewed, delete the xobjects and turn off annotations/comments again. That feels a bit complex.
  • An alternative to the proposal above would be to have a staging xwiki.org instance and use it for writing new docs and publish them only after being reviewed. I feel that this is too painful and would prevent being fluid and we’ll have lots of new docs waiting for validation which isn’t great.
  • Yet another option is to use Change Request again but before that’s possible we would need to fix a few issues that prevent it from being easy to use. So this could be reconsidered once it’s ready for our usage IMO.

Thx