Docs: Use case topic or page type
Problem to solve
Current style guidance for concept topic types states:
Titles to avoid
Avoid these topic titles:
- ...
- Use cases. Instead, incorporate the information as part of the concept.
As Suzanne said in !175157 (comment 2264020055):
Many times they are just lists of how the product works, which is why we've tried to avoid them. But in this case, you truly are showing use cases, or examples of how you'd use these things.
Proposal
Let's:
- Review how we're still using "use case" topics in the docs (contrary to current guidance).
- Identify topics that follow the guidance of not using "Use case" in title but correctly fit the function of showing example use cases.
- Amend the guidance in https://docs.gitlab.com/ee/development/documentation/topic_types/concept.html#titles-to-avoid to allow use case topics that fit specific criteria (proposed):
- Describes example, real-world scenarios or workflows where the feature is useful.
- Is longer than a short bullet list.
Examples in docs
Pages/topics that fit the "use cases" goal:
- https://docs.gitlab.com/ee//administration/maintenance_mode/index.html#an-example-use-case-a-planned-failover
- https://docs.gitlab.com/ee/administration/geo/index.html#use-cases
- https://docs.gitlab.com/ee/ci/caching/index.html#common-use-cases-for-caches
- https://docs.gitlab.com/ee/ci/testing/browser_performance_testing.html#use-cases
- https://docs.gitlab.com/ee/integration/jira/issues.html#use-case-for-closing-issues
- https://docs.gitlab.com/ee/topics/runner_fleet_design_guides/gitlab_runner_fleet_config_and_best_practices.html#real-life-applications-for-a-hypothetical-use-case
- https://docs.gitlab.com/ee/user/group/epics/linked_epics.html#ways-to-use-linked-epics
- https://docs.gitlab.com/ee/user/project/issue_board.html#issue-boards-use-cases
- https://docs.gitlab.com/ee/user/project/milestones/burndown_and_burnup_charts.html#use-cases-for-burndown-charts
Pages/topics that are/should be regular concept topics or part of introduction:
- Occurrences where use case is mentioned in one sentence in a concept topic (skipped here)
- https://docs.gitlab.com/ee/administration/settings/account_and_limit_settings.html#repository-size-limit
- https://docs.gitlab.com/ee/ci/cloud_services/index.html#use-cases
- https://docs.gitlab.com/ee/ci/examples/index.html#cicd-examples
- https://docs.gitlab.com/ee/ci/testing/metrics_reports.html#use-cases
- https://docs.gitlab.com/ee/ci/yaml/needs.html#use-cases
- https://docs.gitlab.com/ee/security/hardening_nist_800_53.md#native-gitlab-user-authentication-configurations
- https://docs.gitlab.com/ee/user/gitlab_duo/use_cases.html
- https://docs.gitlab.com/ee/user/group/index.html#group-structure
- https://docs.gitlab.com/ee/user/project/merge_requests/approvals/index.html#required-approvals
Skipped:
doc/developmentdoc/tutorials
Unsure/to sort:
- https://docs.gitlab.com/ee/ci/testing/fail_fast_testing.html#example-use-case
- https://docs.gitlab.com/ee/user/project/canary_deployments.html#use-cases
- https://docs.gitlab.com/ee/user/project/deploy_boards.html#use-cases (deprecated feature)
- https://docs.gitlab.com/ee/user/project/repository/mirror/troubleshooting.html#transfer-mirror-users-and-tokens-to-a-single-service-account
Who can address the issue
Other links/references
- "Use cases" are mentioned in Docs consistency issues (#330052 - closed)
Edited by Marcin Sedlak-Jakubowski