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.
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:
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).
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.
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.
Hi, I agree with this process.Sounds good to me and I think it helps make sure that users don’t rely on incomplete information while migrating.
Starting today, I’ll systematically ask for reviews on the xwiki chat for all the documents I migrate. For some documents that I’m sure about, I’ll add myself as the reviewer so that they are still marked as reviewed (an “autoreview” process). There are also other advantages of asking for reviews as it helps contributors discover the new documentation location, it provides examples of migrated pages and it gives us a chance to get feedback and suggestions from others.
Do we want to make sure the old page redirects to the new one?
I’m afraid that users with a bookmark to the old page will hit a 404 the next time they need to access their favourite documentation.
Currently, “removing” means removing the content from the section and replacing it with a link (or links) to the corresponding pages in the new documentation. So the pages themselves remain in place, which means existing URLs and bookmarks continue to work. But you actually have anticipated the proposal I’m currently working on. It focuses on what to do with pages that have been fully migrated and only contain links to the new documentation.
But the issue is that a single page from the old documentation is usually split into multiple pages in the new documentation. The same can happen at the section level, where one old section may correspond to several new pages now. In such cases, it’s not obvious which page should be used as the redirect target in the redirect object.
One possible approach would be to redirect to the main/parent page for that topic. For example, Page Editing could redirect to Edit a Page .
I’ll ping in this thread once the proposal is ready. Besides redirects, it also includes ideas around maintaining mappings between old and new pages/sections, automatically updating backlinks, and introducing additional xobjects on documentation pages to help track the migration.
It focuses on what to do with pages that have been fully migrated and only contain links to the new documentation.