Users are confused with gitlab.example.com in API docs
Problem to solve
From the feedback we've long received about the API docs (recent example, GitLab-internal), users are confused about gitlab.example.com in our example URLs:
- Self-managed users don't always realize they need to use their instance's URL.
- SaaS users don't always realize they need to use
gitlab.com.
Further details
This URL is decided in style guide and API topic template.
Proposal
Possible approaches. Modify the API doc template to:
- Include a note above each example that uses the example URL. The note would say that you should use your instance URL, so for example SaaS users should use
gitlab.com. - Start each page with an explanation of the example URL (like above).
- Explain the example URL (like above) for REST API (and how to build the base URL: add /api/v4/ for the current) either in https://docs.gitlab.com/ee/api/ or https://docs.gitlab.com/ee/api/api_resources.html, and then link to it, either from the top of each API page, or from near each example request.
I don't think this is the best approach, but this is the only one I can think of at the moment.
Who can address the issue
TW team, @sselhorn as the style guide DRI