[go: up one dir, main page]
Skip to content

Importers Documentation Revamp

Problem Statement

Our current documentation for importers is fragmented and doesn't align well with user journeys. The separation between group and project importers no longer reflects how the product works, as direct transfer and soon to be implemented offline transfer (based on DT) support both scopes. Additionally, users may get confused when navigating between related documentation pages, such as the 'Migrate groups by direct transfer' page not linking to the 'Reassign contributions and memberships' docs.

Current Documentation Structure Issues

  1. Documentation is split between group and project importers, which doesn't match current product functionality
  2. Possibly: Direct Transfer migration docs are broken into multiple pages that may be difficult to navigate
  3. Missing clear links between related processes in the user migration journey
  4. Old UCM and new UCM documentation mixed together without clear enough distinction
  5. No consolidated view of all import options

Proposed Solution

Restructure importers documentation to:

  1. Create a unified /user/import/ section for all importers

  2. Organize importers by type rather than scope:

    • GitLab-to-GitLab importers
      • Online (Direct Transfer)
      • Offline (to be built)
    • Third-party importers (GitHub, Bitbucket, etc.)
    • General "to GitLab" importer (for converting exports from other systems)

  3. For each importer type, provide clear documentation on:

    • Entry points in the UI
    • Complete process flow including pre and post-migration steps
    • Scope support (group, project, or both)
    • Version requirements and limitations

  4. Clearly separate legacy documentation (pre-17.7) from current documentation

Alignment with UI Flow

The documentation structure should align with how users interact with importers in the UI:

  1. "Import history" in user's "My work", soon to come in group's menu and Admin's menu
  2. Group-level and project-level import options - entry points of the journey
  3. Admin-level import options - entry points of the journey
  4. View of placeholder users (group owners and admins)

API Documentation

Perhaps API documentation should follow the same structure, organized by importer type rather than scope.

Questions for Discussion

  1. There are docs for importing from external solutions, that we don't support in the product, like https://docs.gitlab.com/user/project/import/clearcase/ - should we separate those?
  2. How do we handle the transition period where both pre-17.7 and post-17.7 documentation is needed?
  3. What naming conventions should we use for the different importer types?
  4. How should we structure the navigation between related processes (e.g., migration → reassignment)?

Related Links