Wiki source code of Migrate and Refactor Documentation
Last modified by Vincent Massol on 2026/07/28 21:45
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | As of September 2025, documentation is being refactored, and moved to [[##/documentation##>>xwiki:documentation.WebHome]] root. These steps describe the flow of how to migrate or reorganize existing documentation content from older locations ([["Documentation">>xwiki:Documentation.WebHome]] or [[Extensions>>extensions:Main.WebHome]] wiki) into the [[##/documentation##>>xwiki:documentation.WebHome]] root. Following them helps avoid duplicated work and content, and ensures consistent structure and navigation. | ||
| 2 | |||
| 3 | == Current state of the migration == | ||
| 4 | |||
| 5 | During this migration, sections or whole pages content from both "/Documentation" and Extension sub-wiki have already been moved to "/documentation". In their original locations, these sections have been replaced with links pointing to the newly converted pages. Over time, both the main documentation and the extensions will be fully moved under "/documentation". | ||
| 6 | |||
| 7 | Before starting any migration work, check for [[existing Change Requests>>Community.DocGuide.SaveChanges.WebHome||anchor="HExistingChangeRequests"]] to make sure that no one else is already working on the same page or content. | ||
| 8 | |||
| 9 | {{display reference="Community.DocGuide.CreateNewDocumentation.CommonSteps"/}} | ||
| 10 | |||
| 11 | Two steps are specific to migration: | ||
| 12 | |||
| 13 | * When applying Diataxis, existing pages or sections often mix multiple documentation types. Such content must be split into multiple pages, each with a single purpose and corresponding to a Diataxis type. | ||
| 14 | * Avoid duplication. Make sure the same content is not kept in both the original documentation and the new documentation pages. When content has been moved, properly [[handle the original documentation pages>>Community.DocGuide.MigrateDocumentation.HandleOriginalDocumentationPages.WebHome||anchor="HWhenthePageNoLongerContainsDocumentationContent"]]. | ||
| 15 | |||
| 16 | * If you are creating new documentation, follow the [[Create New Documentation – Flow Guide>>Community.DocGuide.CreateNewDocumentation.WebHome]]. | ||
| 17 | * To update existing documentation pages, follow the process described in [[updating existing pages>>doc:Community.DocGuide.UpdateExistingPages.WebHome]]. | ||
| 18 | |||
| 19 | {{info}} | ||
| 20 | [[FAQ pages>>xwiki:FAQ.WebHome]] will also be progressively converted into proper documentation pages that follow this Documentation Guide. | ||
| 21 | {{/info}} |
