Identify and evaluate longest documentation pages - Content audit
Issue Description
From &3747:
What are the 25 longest pages? Can we optimize/shorten/improve them?
Results
| Page | Wordcount | Stage/Group | Method for addressing length |
|---|---|---|---|
| GitLab CI/CD pipeline configuration reference | 20,178 | Verify/Continuous Integration | &4138 |
| GraphQL API Resources | 18,822 | Auto-generated page | |
| Documentation Style Guide | 11,027 | none/Technical Writing | |
| Project API | 10,607 | Plan/Project Management | |
| Merge requests API | 9,108 | Create/Source Code | |
| Reference architecture: up to 5,000 users | 8,709 | Enablement/Distribution | Intentional decision to have page be this length |
| Reference architecture: up to 3,000 users | 8,709 | Enablement/Distribution | Intentional decision to have page be this length |
| GitLab Managed Apps | 7,934 | Configure/Configure | |
| Issues API | 7,659 | Plan/Project Management | |
| Usage Ping Guide | 7,518 | Growth/Telemetry | |
| Advanced configuration | 6,616 | Verify/Runner | |
| Installing GitLab on Amazon Web Services (AWS) | 6,605 | ||
| GitLab Markdown | 6,490 | Create/Source Code | |
| Services API | 6,361 | ||
| PostgreSQL replication and failover with Omnibus GitLab | 6,217 | ||
| Gitaly | 5,717 | Create/Gitaly | |
| Back up and restore GitLab | 5,500 | ||
| Groups API | 5,494 | ||
| GitLab Container Registry administration | 5,445 | Package/Package | |
| GraphQL API style guide | 5,406 | ||
| Environments and deployments | 5,206 | Release/Release Management | |
| GitLab Architecture Overview | 5,087 | ||
| Configure Charts using Globals | 4,999 | Enablement/Distribution | |
| Users API | 4,988 | ||
| Discussions API | 4,950 | Plan/Project Management | |
| Installation from source | 4,931 |
Observations
Many of the longer pages in this list are pages that we currently don't have much ability to change. The majority of those pages are related to the API, which are generally a laundry list of endpoints and their descriptions. There are other pages in the list that could be broken up or shortened, but while they're on the long side, they don't seem to be unusable. It may be worth waiting for our upcoming content rearchitecture to address these pages as we go, and use this issue (and the content audit) to be aware of them during their revamping.
The one notable exception is the GitLab CI/CD pipeline configuration reference page. It is far and away the largest page, and would benefit from attention sooner than later (especially since it is one of our most highly visited pages). As such, we've created an epic to go ahead and improve the page (which includes making it shorter and breaking it apart, as we can). That effort is being tracked independently of this identification issue.