Reviewing Migrated and Refactored Documentation

[elenicojocariu]

Hello everyone ,

This proposal comes after the discussion about the strategy to review all refactored documentation: Documentation for the XWiki Ecosystem and experimenting with the proposed review process.

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

The Review Dashboard is particularly important because a significant number of documentation pages (500+) were migrated before the WIP-banner workflow was proposed. For many of these pages, the original content has already been removed and replaced with links to the new documentation.

As a result, those pages cannot fully follow the WIP workflow described in the discussion. The Review Dashboard provides a way to track, assign, and complete reviews for these already-migrated pages, ensuring they still receive the same level of review and validation.

The live data of the Review Dashboard would contain the following columns:

• New Doc - all pages with a DocumentationClass object attached. Each page will appear as a link to the new doc page.
• Refactored From - links to the original doc page from which the new doc was created. If empty, the doc is completely new.
• Ready for Review - Yes/No status.
• Reviewer - contributors can assign themselves to review a page. Every page must have a reviewer. If no reviewer is assigned, it means no one has taken responsibility yet. Once a reviewer is assigned, they are responsible for completing the review.

I tried it locally and it currently looks like this

(Please ignore the first 4 rows that are templates from the Documentation Application, I will probably need some help filtering them).

To support this, I propose adding the following properties to DocumentationClass of the Documentation Application:

• RefactoredFrom: String
• Reviewer: List of Users
• ReadyForReview: Static List

Note: There is also the Documentation Review Class, which has two properties: Last Reviewer and Date. But these are different from the newly proposed Reviewer property:

• The Reviewer property indicates who has committed to reviewing a page. It helps track which pages already have someone responsible for the review and which still need a reviewer.
• The Last Reviewer property is completed after the review has been performed, recording who actually completed the review.

To sum up the discussions from the previous forum post and this post regarding the documentation reviewing process, the full workflow would be:

1. When creating or refactoring documentation, the documentation writer adds a WIP banner on the new page.
   • If the page is a refactoring of existing content, the WIP banner should include a link to the original page.
   • A WIP banner should also be added on the original page to indicate that the content is being migrated.
   • The original content should not be removed at this stage.
2. The page automatically appears in the Review Dashboard through its DocumentationClass object.
3. Once the documentation writer considers the page ready for review, they set Ready for Review = Yes in the Review Dashboard.
4. A contributor can then assign themselves as the Reviewer . This indicates that they have taken responsibility for reviewing the page.
5. The reviewer performs the review by:
   • Comparing the new page with the original content (when applicable).
   • Checking content validity, completeness, and compliance with the documentation guidelines.
   • Providing feedback, making corrections directly, or opening a Change Request if needed.
6. The documentation writer addresses the review feedback.
7. Once the reviewer confirms that the page is correct and complete:
   • The reviewer adds on the page the object of type Documentation Review Class and fills in the metadata (Last Reviewer and Review Date).
   • For pages following the WIP workflow, the documentation writer removes the WIP banners.
   • If content was migrated from an existing page, the old content can then be removed and replaced with links to the new documentation.

This dashboard and process will help us clearly see which pages need review, who is responsible for them.

WYT? Thanks!

[elenicojocariu]

BTW the RefactoredFrom property proposed here would also help with automatically updating backlinks (see: Handling Fully Migrated Documentation Pages and Updating Backlinks).

Instead of using Option 2 of the proposal which is adding a new XObject to track the origin of each migrated page, the RefactoredFrom property is directly included in the DocumentationClass.

[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.

[elenicojocariu]

Hi! Thx for the feedback!

I agree that migration is indeed a specific use case and probably should not become part of the DocApp.

However, I think the Review Dashboard solves a more general problem than migration. The migration is what revealed the need for it, but the dashboard could still be useful afterwards to track documentation reviews.

So, while the migration-specific information (the migration XClass/ XProperty if we rework the existing ReviewClass) could remain part of the temporary migration work, the review dashboard itself could potentially be kept as a general documentation review tool if we see that it is useful.

@vmassol

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.

I actually like the CR review workflow very much: reviewers can review a change, request modifications, use comments to explain what needs to be changed, and publish once everything is ready. However, some parts of CR are less convenient for documentation:

• making changes in the doc is not as easy because contributors cannot use the WYSIWYG editor
• the Documentation Application has many fields and often requires using the object editor which is not as nice as the WYSIWYG
• reading diffs is not the easiest way to review documentation.

So I think the dashboard can start as a temporary solution for the migration. If it proves useful, we could consider keeping it as a general Documentation Review Dashboard for XWiki.org specifics, while also looking at possible improvements for the Change Request Application.

[vmassol]

@elenicojocariu

So, while the migration-specific information (the migration XClass/ XProperty if we rework the existing ReviewClass) could remain part of the temporary migration work, the review dashboard itself could potentially be kept as a general documentation review tool if we see that it is useful.

Yes, and we already have such a Review Dashboard, it’s at https://www.xwiki.org/xwiki/bin/view/DocApp/#HDocumentationReviews on xwiki.org for example.

@elenicojocariu

However, some parts of CR are less convenient for documentation:

• making changes in the doc is not as easy because contributors cannot use the WYSIWYG editor

Haven’t tried it but are you sure? I’m asking because Loading... seems to hint that it’s the opposite. Maybe you mean the ability to use the Form/Inline editor to make changes? If so, that’s indeed Loading... that we need.

@elenicojocariu

the Documentation Application has many fields and often requires using the object editor which is not as nice as the WYSIWYG

Isn’t that the same thing as the 1st item? ie Loading... ?

@elenicojocariu

• reading diffs is not the easiest way to review documentation.

The rendered diff is supposed to work in a cluster I think (with some hacks), @surli could you confirm? I know there’s still an open issue to fix it properly but I remember you mentioning that it can work.

I noticed also Loading... which, if still true, would need to be fixed too.

@elenicojocariu

So I think the dashboard can start as a temporary solution for the migration. If it proves useful, we could consider keeping it as a general Documentation Review Dashboard for XWiki.org specifics, while also looking at possible improvements for the Change Request Application.

I’d like to keep our review process for docs as simple as possible and move to CR ASAP (once the limitations/bugs have been fixed).

From what I see, all that we’re missing is the “ready for review” and the “assigned reviewers” fields, right? The problem with the “ready for review” is that it doesn’t work a second time so it works for migrations but not for general reviews.

The second problem I see is that if we had a strong process this means changing the docs very often and I don’t like this since it makes the history hard to read and cluttered with no benefit to the content of the docs. Basically the review states should be saved in a different doc ideally, which is exactly what the CR app does.

So my feeling is that right now we don’t need such a complex process. We just need you to be the maintainer of the docs (you already are), and ask devs on xwiki for reviews (you were supposed to do that every day btw AFAIU, I didn’t see it but maybe I missed it), and discuss with the reviewers to fix the issues found and then set the last reviewer/date.

In short, before trying to do something complex, let’s start the simple process and try it first.

WDYT?

Thanks

[surli]

@vmassol

@elenicojocariu

• reading diffs is not the easiest way to review documentation.

The rendered diff is supposed to work in a cluster I think (with some hacks), @surli could you confirm? I know there’s still an open issue to fix it properly but I remember you mentioning that it can work.

It mostly works, there might be problems with display of images but that’s it.

[elenicojocariu]

@vmassol

Haven’t tried it but are you sure? I’m asking because Loading… seems to hint that it’s the opposite. Maybe you mean the ability to use the Form/Inline editor to make changes? If so, that’s indeed Loading… that we need.

Indeed, I was referring to the in-line editor.

The in-line editor is what gets used by default when a page is created. However, when you create a page via “request creation”, you need to switch to the “object editor” and manually add the Doc objects.

Also, inside a CR, the “Edit” button (from the “Proposed changes” tab) opens the page using the in-line editor, which makes the DocApp fields non-editable. In that case, you need to open the page in the in-line editor first and then switch to the object editor in order to edit those fields.

For the diffs, locally I’m getting some errors when using it with the DocApp, but I need to investigate further to understand what’s going on and open a ticket if needed.

@vmassol

So my feeling is that right now we don’t need such a complex process. We just need you to be the maintainer of the docs (you already are), and ask devs on xwiki for reviews (you were supposed to do that every day btw AFAIU, I didn’t see it but maybe I missed it), and discuss with the reviewers to fix the issues found and then set the last reviewer/date.

I was looking for a way to make things easier for both the reviewers and me, so we can get everything that already exists reviewed.

A table or review dashboard can help a lot with this. It would let reviewers assign docs to themselves and clearly see what each person has already taken for review, as well as the status. Without something like this, I can still send a batch of docs with their original Doc pages and ask for reviews, but it becomes harder to coordinate. For example, two reviewers might start working on the same page and only later realize that someone else already took it. The table would have forced them to assign and the option to review later, but we would’ve known that someone took responsibility for that doc page. In the meantime, for new docs we could use the CR process, while also improving it over time.

Thanks!

[vmassol]

@elenicojocariu

Also, inside a CR, the “Edit” button (from the “Proposed changes” tab) opens the page using the in-line editor, which makes the DocApp fields non-editable. In that case, you need to open the page in the in-line editor first and then switch to the object editor in order to edit those fields.

I think there’s some terminology issues here

• Inline editor = form editor
• inplace editor = the wysiwyg editor that transforms the view into an edit mode

By default the Edit button uses the inplace editor.

In any case, I think your issue is Loading...

@elenicojocariu

A table or review dashboard can help a lot with this. It would let reviewers assign docs to themselves and clearly see what each person has already taken for review, as well as the status. Without something like this, I can still send a batch of docs with their original Doc pages and ask for reviews, but it becomes harder to coordinate. For example, two reviewers might start working on the same page and only later realize that someone else already took it. The table would have forced them to assign and the option to review later, but we would’ve known that someone took responsibility for that doc page. In the meantime, for new docs we could use the CR process, while also improving it over time.

Again why bother about something that doesn’t even exist Right now, AFAIK you’ve not asked anyone to do any review on the #xwikichat. If you do, then someone will reply and everyone will know that person is doing a review of it. Sure it doesn’t scale but we’re not talking one review per day or so asked. ofc if you start asking for 500 reviews, it won’t work but even witha process it won’t work. When we talked we said that you should ASAP ask every day for a review on the #xwiki chat. What’s holding that?

Thanks