Reviewing Migrated and Refactored Documentation

[vmassol]

@elenicojocariu

To make it easier for contributors to review refactored documentation pages, I propose creating a Review Dashboard, a centralized page with live data.

We have 2 choices:

1. Consider that the migration use case is a feature we want in the documentation application
2. Consider the the doc migration is something specific to our work on xwiki.org and don’t include that concept in the documentation application

From what I see, if we want 1) then we need to:

• Add the XClass defined in Handling Fully Migrated Documentation Pages and Updating Backlinks to the doc app
• Update the existing Review dashboard to add a “Refactored from” column. That column could be hidden by default, or we could make it displayed if we find at least one doc in the wiki using the migrated xobject.

If we want 2), then we need to implement it fully on xwiki.org and provide a new dashboard indeed.

@elenicojocariu

Refactored From - links to the original doc page from which the new doc was created. If empty, the doc is completely new.

Note: The information would be found from the migration xobject.

I think all the other fields could come from the existing DocumentationReviewClass, by changing it a bit. See below.

@elenicojocariu

3. Once the documentation writer considers the page ready for review, they set Ready for Review = Yes in the Review Dashboard.

I think this is useful not just for migrations but anytime someone makes substantial changes to a page and wants a review of it. OTOH this is clearly a use case for the Change Request Application, so I’m wondering if we’re not reinventing the wheel here… Maybe we should review all that is missing in the CR App so that we could use it in a comfortable manner? Now it’s likely that fixing the CR app will take way longer than implementing this here.

Thus, I think I agree about doing 2 things:
A) Review all that is missing in the CR App so that we could use it in a comfortable manner, create jira issues for it and then reply in this thread (for ex) with the list of jira issues that would be needed so that we have a record of it + discuss it with @surli
B) Implement option 2) above and not 1) with the idea that one day we would use the CR app to review doc migration proposals or doc update proposals. This makes the Documentation Migration Dashboard a temporary page available only on xwiki.org and that we will remove after the migration is over.

@elenicojocariu

Reviewer: List of Users

I propose to name it assignedReviewer. Note the lower case start for property names.

@elenicojocariu

If content was migrated from an existing page, the old content can then be removed and replaced with links to the new documentation.

Based on proposal at Handling Fully Migrated Documentation Pages and Updating Backlinks I’d rather implement this automatically by removing content and adding a new xobject (of type DocumentationMigratedClass, a new xclass). We should have a class sheet for DocumentationMigratedClass that would automatically list all link, with some explanation text (and an automatic redirect if there’s a single new page).

@elenicojocariu

, the full workflow would be:

I think the workflow is a bit complex and there’ll need to be a lot of sync between the doc writer and the doc reviewer but let’s try it and we can improve it as we progress.