Move Monitor docs to fit the new IA structure
Problem to solve
I'm creating this issue to outline the massive quantity of work that needs to happen to implement the information architecture agreed upon by UX (@nadia_sotnikova, based on UX research in #209889 (closed), and this resulting card sort) and the PM team for Monitor (@kbychu, @dhershkovitch, @sarahwaldner).
I want to be very clear on the following points before beginning work:
- The left-hand navigation menu will get a new item, "Operations"
- UX and the PMs requested the URLs be updated to match the left-hand navigation
- The proposed IA (
doc/operations
) violates the current folder structure recommendations in the style guide - the UX research showed users found the currentdoc/user/project/operations/
location unintuitive and unfindable because it doesn't match the GitLab UI, which starts with Operations. UX and the PMs have explicitly agreed the breaking IA change is necessary. I'm cc'ing @cnorris, @susantacker, and @clenneville because I want to be clear that I'm intentionally violating an IA precept of our style guide because we are in agreement the style guide is wrong - Multiple new pages will be carved out of https://docs.gitlab.com/ee/user/project/integrations/prometheus.html - a 7000+ word monster of a page. I expect to extract at least 7 separate pages from that page.
- This work will require quite a few MRs to complete.
Further details
Proposal
This bulleted list builds off of Nadia's IA design, and adds more pages I am aware of. The left-hand menu should be updated first to create the Operations top-level menu with what items currently exist, without moving page locations. Then begins a simultaneous combination of 1) moving files to their new home 2) pulling content out of the giant Prometheus integration page and 3) updating the menu to reflect the new page locations.
-
✅ Operations (currently https://docs.gitlab.com/ee/user/project/operations/index.html)-
✅ Metrics (currently a stub)-
❌ Overview (does not currently exist) - Getting Started
- → (CREATE from prometheus.html#getting-started)
- → (CREATE from prometheus.html#getting-metrics-to-display-on-the-metrics-dashboard)
- Using Prometheus (Not sure. Will be easier to see once I prune so much OTHER data out of the Prometheus page.)
-
✅ Dashboards (CREATE from prometheus.html#using-the-metrics-dashboard, prometheus.html#chart-context-menu, and prometheus.html#dashboard-annotations)- Creating Dashboards (CREATE FROM the following)
- → (prometheus.html#defining-custom-dashboards-per-project)
- → (prometheus.html#select-an-environment)
- → (prometheus.html#select-a-dashboard)
- → (prometheus.html#mark-a-dashboard-as-favorite)
- → (prometheus.html#add-related-links-to-custom-dashboards)
-
✅ Dashboard settings (https://docs.gitlab.com/ee/user/project/operations/dashboard_settings.html) -
✅ Dashboard YAML properties (CREATE from prometheus.html#dashboard-yaml-properties) -
✅ Panel types from dashboards (CREATE from prometheus.html#panel-types-for-dashboards) - Templating variables for metrics dashboards (CREATE from #templating-variables-for-metrics-dashboards)
- Creating Dashboards (CREATE FROM the following)
- Adding metrics and alerts (CREATE from prometheus.html#adding-custom-metrics)
- Generic alerts
- Metrics settings (CREATE from ??? and prometheus.html#metrics-dashboard-visibility)
-
✅ Embedding metrics charts within GitLab flavored Markdown (CREATE from prometheus.html#embedding-metric-charts-within-gitlab-flavored-markdown)- → (prometheus.html#embedding-gitlab-managed-kubernetes-metrics
- → (prometheus.html#embedding-metrics-in-issue-templates
- → (prometheus.html#embedding-metrics-based-on-alerts-in-incident-issues
- → (prometheus.html#embedding-cluster-health-charts-ultimate
-
✅ Embedding Grafana charts (CREATE from prometheus.html#embedding-grafana-charts)
-
- Troubleshooting (CREATE from prometheus.html#troubleshooting)
- Libraries https://docs.gitlab.com/ee/user/project/integrations/prometheus_library/index.html
- Cloudwatch https://docs.gitlab.com/ee/user/project/integrations/prometheus_library/cloudwatch.html
- HAProxy https://docs.gitlab.com/ee/user/project/integrations/prometheus_library/haproxy.html
- Kubernetes https://docs.gitlab.com/ee/user/project/integrations/prometheus_library/kubernetes.html
- NGINX https://docs.gitlab.com/ee/user/project/integrations/prometheus_library/nginx.html
- NGINX Ingress https://docs.gitlab.com/ee/user/project/integrations/prometheus_library/nginx_ingress.html
- NGINX Ingress VTS https://docs.gitlab.com/ee/user/project/integrations/prometheus_library/nginx_ingress_vts.html
-
- Alert Management (https://docs.gitlab.com/ee/user/project/operations/alert_management.html)
-
✅ Tracing (https://docs.gitlab.com/ee/user/project/operations/tracing.html) - Error Tracking (https://docs.gitlab.com/ee/user/project/operations/error_tracking.html)
- Logs (??? I'm not sure here - Kubernetes pod logs will be under infrastructure > cluster monitoring)
-
✅ Incident Management (https://docs.gitlab.com/ee/user/incident_management/index.html)-
✅ Status Page (https://docs.gitlab.com/ee/user/project/status_page/)
-
-
✅ Feature Flags (https://docs.gitlab.com/ee/user/project/operations/feature_flags.html)
-
Who can address the issue
Me.
Other links/references
- Related to #209889 (closed) where Nadia did the card sort.
- Related to #209893 (closed) where Nadia created the proposed IA.
- Related to #208280 (closed), an old issue that can be resolved by this work
- Related to #217974 (closed) which was my first attempt to do this work before the UX card sort
- Related to #207609 (closed) which is another problem that can likely be solved by this work