Handling Fully Migrated Documentation Pages and Updating Backlinks

Development
1

Hello everyone,

This proposal is about how to handle fully migrated documentation pages and automate the process of updating backlinks.

Context

The current documentation migration guide explains how to migrate content from the old documentation to the new documentation space: Handle Original Documentation Pages. However, it does not define what should happen once the migration is complete. At that point, an old (original) documentation page may contain only links to the corresponding pages in the new documentation. Examples include: Page Editing, Version Control.

A strategy for handling pages whose content has been fully migrated should be defined.

A simple solution would be to replace the old content with a Redirect Object pointing to the corresponding page in the new documentation. But many old documentation pages do not map to a single new page. Instead, they have been split into multiple pages.

Possible solutions

Option 1: Redirect to the Parent Page

When an old page has been split into multiple pages, redirect to the most relevant parent or overview page.

Example:

  • Old page: Page Editing → Redirect target: Edit a Page. Any anchor saved from Page Editing would point to Edit a Page. The disadvantage is that the user needs then to browse through the new doc to find the exact information they need.

Option 2: Introduce a new “Migration” XObject

Add a new XObject to new documentation pages that stores the old page and, if it’s the case, the old section anchor.

This keeps the relationship between old and new documentation, even when one old page or section is split into multiple pages.

If a user opens an old URL (or bookmark) that now corresponds to multiple new pages, we could automatically display a list of all the new pages that reference that old page or section through the XObject, instead of redirecting to a single page. The idea is similar to the “Documentation” button in the Extension pages, which lists documentation pages associated with a technical identifier, (e.g., Documentation for extension: “User Profile” ).

Updating the Backlinks

Many pages in the wiki still contain links to the old documentation. To complete the migration, these backlinks could be updated automatically (there are many many backlinks). One idea is to maintain a mapping between old and new pages:

OldPage[#anchor] = NewPage[||anchor]

Then use a script to:

  • update backlinks automatically,
  • replace links starting with Documentation. or xwiki:Documentation. ,
  • generate redirects when the migration is complete.

We could iterate through the “migration” XObjects and update backlinks based on the mapping, or iterate through pages that contain backlinks to old documentation pages and update them.

WYT about these aproaches? Thanks!