Improve import documentation clarity on resource constraints and limits
Problem
The group import documentation at https://docs.gitlab.com/user/group/import/ needs improvements to better serve users on GitLab.com and GitLab Dedicated, and to clarify the limits that apply to migrations.
Improvement 1: Clarify resource constraints for GitLab.com and Dedicated users
Current state: The documentation mentions that migrations are available on GitLab.com, GitLab Self-Managed, and GitLab Dedicated, but doesn't adequately explain the key difference in how users can address performance issues.
Suggested improvement: Add a section that clarifies:
- On GitLab.com and GitLab Dedicated, users cannot directly control infrastructure resources (CPU, memory, Sidekiq workers) to optimize migrations
- Self-Managed users have the ability to add Sidekiq workers and adjust infrastructure to improve migration performance
- This distinction should be highlighted early in the documentation, perhaps in the "Reducing migration duration" section, to set proper expectations for GitLab.com and Dedicated users
Rationale: Users on GitLab.com and Dedicated may attempt troubleshooting steps from the "Reducing migration duration" section that are not applicable to their deployment model, leading to frustration.
Improvement 2: Clarify the limits table
Current state: The "Limits" section has a table with entries like:
- "6" - Maximum number of migrations permitted per minute per user
- "5 minutes" - Maximum number of seconds until an empty export status on source instance is raised (note: the unit description is confusing)
Suggested improvement:
- Clarify what each limit applies to (e.g., is the "6" limit per migration, per API call, or per group/project being migrated?)
- Fix the "5 minutes" entry which says "Maximum number of seconds" but the value is in minutes - clarify the actual unit and what triggers this timeout
- Add examples or scenarios to help users understand the practical impact of each limit
- Consider adding a note about what happens when limits are exceeded (e.g., does the migration fail, pause, or get queued?)
Rationale: Users need clear understanding of what limits they may encounter and how those limits affect their migration strategy.
Improvement 3: define and/or explain technical terms
Throughout the doc page, the term relation is used but not described anywhere. Users not familiar with database terminology may have difficulty understanding the content.
We typically assume this technical knowledge in the development documentation, but this page is for regular users.