Add product description for new teams map - #38660
Conversation
Preview links (active after the
|
This comment has been minimized.
This comment has been minimized.
OliviaShoup
left a comment
There was a problem hiding this comment.
Thanks for the PR! Got some feedback. Reading this and #38661 together which affects everything
This PR adds the what and why of team hierarchies. #38661 adds the how — four setup methods. Two consequences:
- The closing sentence of line 85 is duplicated near-verbatim as line 76 of #38661 ("...visit the [Teams Map] in the Datadog Internal Developer Portal (IDP)").
- The same broken Teams Map URL is introduced in both —
[7]here,[40]there.
There's also a shuffle: this PR removes the Teams API pointer from manage.md, while #38661 adds a Teams API link on the other page.
I think we can consolidate the setup methods from #38661 into this section, so what/why/how live together. _index.md would then just cross-link, which matches its existing pattern. It already defers SAML detail to another page and closes with "To customize your team, see [Team Management]." That removes the duplicated sentence, the duplicated URL, and the API-pointer shuffle in one move. I've left the same note on #38661.
Otherwise!
Three blocking items, detailed inline: the removed GovCloud support warning, four inbound links broken by the heading rename, and the Teams Map URL with a hardcoded one-hour time window. The rest are line edits.
| This feature is not supported for your selected Datadog site ({{< region-param key="dd_site_name" >}}). | ||
| </div> | ||
| {{< /site-region >}} | ||
| ## Team hierarchies |
There was a problem hiding this comment.
Two blocking items on this heading change.
1. The GovCloud warning was dropped. master has this immediately under the old heading:
{{< site-region region="gov,gov2" >}}
<div class="alert alert-warning">
This feature is not supported for your selected Datadog site ({{< region-param key="dd_site_name" >}}).
</div>
{{< /site-region >}}
It isn't re-added anywhere in this PR. If hierarchies still aren't supported on gov/gov2, removing this actively misleads US1-Fed customers. Could you confirm whether Teams Map shipped to gov sites, or whether this came out accidentally during the rewrite?
2. Renaming the heading breaks four inbound links. The anchor changes from #subteams-hierarchical-teams to #team-hierarchies, and these four pages point at the old one:
content/en/account_management/guide/teams-and-access.md:43content/en/internal_developer_portal/_index.md:97content/en/internal_developer_portal/eng_reports/_index.md:46content/en/internal_developer_portal/catalog/set_up/ownership.md:65
They all need updating in this PR, otherwise those links land on the page but not the section.
| [3]: /account_management/scim/ | ||
| [5]: /api/latest/teams/#add-a-member-team | ||
| [6]: /incident_response/on-call/ | ||
| [7]: https://app.datadoghq.com/software?env=%2A&fromUser=true&refresh_mode=sliding&selectedComponent=team&start=1785444148521&end=1785447748521 |
There was a problem hiding this comment.
This URL has a hardcoded one-hour time window and needs replacing.
The start and end values decode to 2026-07-30 20:42:28 → 21:42:28 UTC, so every reader who clicks it is pinned to that single hour, permanently. fromUser=true, refresh_mode=sliding, and selectedComponent=team are also copy-paste artifacts from a browser session.
A clean app link without the query string is what's needed here. The same URL appears as [40] in #38661, so both need the fix.
Separately: [5] is now orphaned. Removing the "use the [Teams APIs][5]" sentence leaves [5]: /api/latest/teams/#add-a-member-team defined but unused (it's used once on master, zero times here). Either drop the definition or bring the API pointer back — worth reading alongside #38661, which adds a Teams API link on the other page.
Co-authored-by: Olivia Shoup <116908616+OliviaShoup@users.noreply.github.com>
Co-authored-by: Olivia Shoup <116908616+OliviaShoup@users.noreply.github.com>
What does this PR do? What is the motivation?
Merge readiness
For Datadog employees:
<name>/<description>convention and include the forward slash (/). If you've already created your PR with an incorrect branch name, please rename your branch and open a fresh PR./reviewto run an automated check that catches common issues before a Documentation team member reviews your PR.AI assistance
Additional notes