Hello, 
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!