Use the `ReviewClass` for Documentation Quality and Validity

Development
,
1

Hello, :waving_hand:

This proposal is about having a structured process of reviewing documentation that is being refactored (and not only).

Proposal: Use the ReviewClass for Documentation Quality and Validity

Context: The ReviewClass was proposed in Proposal 3 and is already implemented in the Documentation Application. It was initially meant to mark reviewed content from the perspective of the Documentation Guidelines. Reviewed pages are tracked in: Documentation Reviews.

Now, it is proposed to extend its usage to also validate the actual content: whether the information is accurate, complete and correctly understood and conveyed in the content.

Proposed workflow

After refactoring content into new location, the contributor should request a review. This can be done by sending a message in the xwiki chat, either addressed to a specific person (e.g., the original author of the documentation page/the developer of the feature), or not specified. The contributor specifies the type of review needed:

  • Validity review: content is accurate, complete, correctly conveyed and understood.
  • Quality review: content, location, navigation comply to the Documentation Guide.

The reviewer will add an object of type ReviewClass and fill-in with a date and its name as a “Last reviewer”, and then provide the feedback. (A contributor can’t put their own name as a reviewer.) For providing the feedback there are the following options:

  • Option 1: Use the xwiki chat to share the improvements.
  • Option 2: Use the Annotations (if enabled).
    ** Currently, comments (and implicitly annotations) are disabled on xwiki.org (Forum proposal). Annotations are fast and could help at tracking whether the feedback was correctly addressed.

Question: Should annotations be re-enabled, or is the chat preferred? Personally, I’m in favor for enabling annotations on the Main wiki, as it’s easier to check if the feedback from the reviewer has been applied.

The advantages of having a structured way of reviewing documentation:

  • Prevents losing or misinterpreting information.
  • Provides checks for documentation validity beyond just following the documentation guide.
  • Ensures content is accurate.

Additional Proposal: Work in Progress Visibility

Add a step in the Migrate and Refactor Documentation to include a “WIP” banner on pages being refactored. The “WIP” banners will also include links between the current and refactored documentation, allowing users to easily navigate between the pages under refactoring and their updated versions.

WYT? Thanks!

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