Skip to content

Freshness work on /admin category#25562

Merged
akristen merged 15 commits into
docker:mainfrom
akristen:admin-category-rework
Jul 15, 2026
Merged

Freshness work on /admin category#25562
akristen merged 15 commits into
docker:mainfrom
akristen:admin-category-rework

Conversation

@akristen

@akristen akristen commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Summary

Simplifies the /admin category by removing duplicated content and reframing it around Docker Home. Concepts now live on overview pages; procedures live on one management page per level.

  • admin/_index.md: Reframed around Docker Home (retired the Admin Console framing); trimmed the hierarchy section.
  • company/_index.md: Dropped duplicated "Key features," made it the canonical home for the company owner concept, and collapsed the Manage/SSO/SCIM grid cards.
  • company/manage.md: Merged the three manage/ pages into one leaf page (aliases preserved) so all company procedures live in one place.
  • organization/_index.md: Streamlined members and consolidated the grid to four entry points; fixed broken/linkless cards.
  • Cross-links & FAQ: Added company/org cross-links, trimmed company-faqs.md to point at canonical concepts, and relabeled the create page to "Setup."

To do

  • Validate seat avoidance for company owners — the unverified "keep access without a seat" workaround was removed; confirm the real behavior and document or drop it.
  • Admin Console audit (separate PR) — sweep /admin for stale navigation, app.docker.com/admin links, and menu labels now that it's not part of Docker Home.
  • Link "Docker Home" consistently across overview pages.
  • Verify anchors/aliases in the built site before merge.

akristen and others added 10 commits July 14, 2026 07:48
Collapse the duplicated invite procedures (Docker ID/email, CSV, API) in company/manage/users.md into a pointer to organization/manage/members.md, which is now the single source of truth. Preserve the company-level Users page resend flow and add a bidirectional callout in members.md for the company invite entry point.

Co-authored-by: Cursor <cursoragent@cursor.com>
Combine company/manage/organizations, owners, and users into a single company/manage/_index.md with anchored sections for organizations, owners, and members. Carry over all prior page aliases so old URLs continue to resolve, and repoint inbound links in company/_index.md, new-company.md, and the members.md callout to the merged page anchors.

Co-authored-by: Cursor <cursoragent@cursor.com>
Move company/manage/_index.md to company/manage.md so Manage is a single page alongside Create, with no Manage section or category. Fix relative links for the new depth and repoint new-company.md and the members.md callout to manage.md.

Co-authored-by: Cursor <cursoragent@cursor.com>
Reorganize company/manage.md into task-based sections (add organizations, company owners, invitations, add seats, teams) and rewrite the intro to describe managing organizations from Docker Home. Document the company-level Users invite and resend flows directly, including choosing the target organization during invite, instead of deferring to the organization members page. Tighten the owner add/remove steps and drop the video resources section.

Co-authored-by: Cursor <cursoragent@cursor.com>
Move the company-owner seat-avoidance guidance and the nested-org Business-subscription downgrade behavior from company-faqs.md into manage.md, making the Manage doc the canonical source. Trim the corresponding FAQ answers to concise, standalone entries that link to the canonical sections, preserving the FAQ page.

Co-authored-by: Cursor <cursoragent@cursor.com>
Move the conceptual company owner content (role, access, and seat behavior) from manage.md into the company overview, where conceptual content belongs, and fold in the ten-owner limit from Key features. Leave the add/remove owner procedures in manage.md under a short pointer, and repoint the company FAQ seat answer to the overview concept section.

Co-authored-by: Cursor <cursoragent@cursor.com>
Replace Docker Admin Console references with Docker Home (linking to app.docker.com), add a Docker Home section above the hierarchy carrying the former Admin Console feature descriptions, and remove the Admin Console features section that no longer maps to the UI. Trim the hierarchy lead-in so it no longer repeats the intro.

Co-authored-by: Cursor <cursoragent@cursor.com>
Consolidate the organization overview grid to core entry points (Onboard, Manage members, Activity logs, and a single Security card linking to the enterprise security section) instead of scattered per-feature security cards. Add an upward cross-link to the administration hierarchy, tighten the organization members section, and point role detail to Roles and permissions.

Co-authored-by: Cursor <cursoragent@cursor.com>
Trim the Company section of the administration overview to link down to the company owners concept in the company overview instead of restating the role, and remove the inaccurate claim that company owners never occupy a seat.

Co-authored-by: Cursor <cursoragent@cursor.com>
Collapse the three Manage grid cards into a single Manage your company card and merge the SSO and SCIM cards, removing the stale manage anchors. Drop the Key features section, reframe the Admin Console reference as Docker Home, add an upward link to the administration hierarchy, and restructure the company owners concept. Remove the unverified seat-avoidance workaround from the overview and the company FAQ, and relabel the create page sidebar entry to Setup.

Co-authored-by: Cursor <cursoragent@cursor.com>
@akristen akristen self-assigned this Jul 14, 2026
@akristen akristen added the area/admin Relates to Docker Admin label Jul 14, 2026
@netlify

netlify Bot commented Jul 14, 2026

Copy link
Copy Markdown

Deploy Preview for docsdocker ready!

Name Link
🔨 Latest commit b20eba9
🔍 Latest deploy log https://app.netlify.com/projects/docsdocker/deploys/6a56a8197febed0008681ce5
😎 Deploy Preview https://deploy-preview-25562--docsdocker.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

docker-agent

This comment was marked as resolved.

akristen and others added 5 commits July 14, 2026 10:04
Repoint Next steps and the create-company pointer in new-company.md and the company-owner NOTE in organization members to the actual manage.md headings (add-more-organizations, company-invitations, company-owners, invite-members-to-an-organization). Addresses the critical docker-agent review on PR 25562.

Co-authored-by: Cursor <cursoragent@cursor.com>
Wrap prose to 80 characters and tighten wording across the admin,
company, and organization pages. Improve FAQ description and
organization keywords for SEO, and fix a few style-guide issues
(contractions, "click here" phrasing, present-tense verbs).

Co-authored-by: Cursor <cursoragent@cursor.com>
Lead the Organization hierarchy entry with what an organization is rather
than the owner role, avoiding duplication with the organization overview.
Restore the company owner seat-avoidance guidance to the company FAQ:
reassign organization ownership and leave the organization to keep
seat-free company-owner access.

Co-authored-by: Cursor <cursoragent@cursor.com>
Replace remaining "Admin Console" and "Docker Admin Console" references
with "Docker Home" across the company category, and tidy adjacent
cross-links and copy.

Co-authored-by: Cursor <cursoragent@cursor.com>
Point the admin overview security grid entry at /enterprise/security/, lead the
intro with what organization and company owners can do, and reword the awkward
team description in the organization overview.

Co-authored-by: Cursor <cursoragent@cursor.com>
@akristen akristen requested a review from aevesdocker July 14, 2026 22:00
@akristen akristen marked this pull request as ready for review July 14, 2026 22:00

@docker-agent docker-agent left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assessment: 🟢 APPROVE

The PR cleanly consolidates four manage/ sub-pages into a single manage.md leaf page, refreshes the admin overview and company/org index pages, and adds the appropriate aliases for the retired URLs. No missing redirects, no broken anchors, and Markdown structure is clean throughout.

One terminology nit in the new manage.md — see inline comment.

{{< summary-bar feature_name="Company" >}}

After creating a company, you can manage multiple organizations from Docker
Home. Company owners can use the company portal to invite users to specific

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Use "Docker Home" instead of "company portal"

The term "company portal" is not a defined Docker product name. The Docker style guide establishes "Docker Home" as the product name (formerly "Admin Console"). The sentence currently reads:

Company owners can use the company portal to invite users to specific organizations…

Suggest replacing "company portal" with "Docker Home":

Company owners can use Docker Home to invite users to specific organizations…

@docker-agent docker-agent left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assessment: 🟢 APPROVE

The changes are clean. All deleted pages have proper aliases in the replacement . Cross-links and anchors verified. No missing redirects, no broken links, no AI-isms, no high/medium issues found.

1. Sign in to [Docker Home](https://app.docker.com) and select
your company.
1. Select **Managed organizations**.
1. Select **Add organization**, then choose an organization from the dropdown.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[LOW] "dropdown" should be "drop-down" (hyphenated) for consistency

The new manage.md file uses "dropdown" (unhyphenated) in this step, while every other reference in the changed files and existing codebase uses the hyphenated form "drop-down" (e.g., "top-left account drop-down" in members.md).

Suggestion: change "from the dropdown" to "from the drop-down".

1. Choose how you want to invite members:
- To invite individual users, select **Emails or usernames**.
- To invite groups of users, select **CSV upload**.
1. Add user(s) to an organization by choosing **Select an organization**.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[LOW] "user(s)" is informal — write "users" or restructure the sentence

The parenthetical plural (s) is informal and inconsistent with documentation style. Since this step is about adding members in bulk or individually, "users" without the parenthetical works for both cases.

Suggestion: "Add users to an organization by choosing Select an organization."

@docker-agent docker-agent left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assessment: 🟡 NEEDS ATTENTION

One medium-severity style issue in the changed lines. All redirects are in place (deleted pages covered by aliases: in manage.md), anchor links verified, no AI-isms found in new content.

A company provides a single point of visibility across multiple organizations,
simplifying organization and settings management.

A company provides a single point of visibility across multiple

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Word collision: "organizations" then "organization" in the same sentence

The sentence reads: "A company provides a single point of visibility across multiple organizations, for centralized organization and settings management."

The word "organization" (used here as a modifier meaning administrative structure) appears immediately after "organizations" (plural, referring to Docker organizations). A reader scanning the sentence must switch between two different senses of the same root word, which creates unnecessary friction.

Suggested rewrite:

A company provides a single point of visibility across multiple organizations, for centralized management of organizations and settings.

Or more concisely:

A company provides a single point of visibility and centralized management across multiple organizations.

@aevesdocker aevesdocker left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So fresh and so clean

@akristen akristen merged commit 4597b3d into docker:main Jul 15, 2026
21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/admin Relates to Docker Admin

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants