[docs-scanner] Unclear policy change timing in organization policies overview

Open Beginner friendly
  • Is something wrong?
#26,555 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@Mhdomer is already working on this.

Since Nov 7, 2026.

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
89/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
markdown
Domain
documentation

Research direction

The issue identifies content/manuals/ai/governance/organization/policies/_index.md and the linked network.md, filesystem.md, and mcp.md pages. Read the overview section alongside the three “When changes take effect” sections to verify the timing descriptions. Update the overview to clarify that syncing takes up to five minutes and that policy type determines the evaluation point; done when it no longer implies an extra delay.

Written by the indexing model from the issue text.

Description

File: content/manuals/ai/governance/organization/policies/_index.md

Issue

The "When policy changes reach developers" section creates confusion about timing by stating:

Policy changes reach developer machines within 5 minutes. When a synced change takes effect also depends on the policy type.

This phrasing suggests there are two separate delays: (1) a 5-minute sync delay, and (2) an additional type-specific delay after syncing. However, the individual policy pages all describe immediate effect after the sync completes:

  • network.md: "Once a policy change has synced to the developer's machine, it applies immediately to subsequent requests."
  • filesystem.md: "Once a policy change has synced to the developer's machine, it applies the next time a sandbox starts."
  • mcp.md: "Once a policy change has synced to the developer's machine, use-time rules apply to subsequent governed MCP requests."
Why this matters

Readers trying to understand when their policy changes will take effect are left uncertain whether there's a 5-minute delay plus additional waiting, or just the 5-minute sync delay. The phrase "When a synced change takes effect also depends on the policy type" implies additional delays beyond syncing, but the linked pages describe only the sync delay.

Suggested fix

Clarify that the 5-minute sync is the only delay, and that "when it takes effect" refers to the evaluation point (per-request vs. sandbox start), not an additional delay. For example:

Policy changes reach developer machines within 5 minutes. Once synced, when the change applies depends on the policy type: network and MCP policies apply to subsequent requests, while filesystem policies apply when a sandbox starts.

Or link directly to the specific sections without the ambiguous "also depends" phrasing:

Policy changes reach developer machines within 5 minutes. For when changes apply after syncing, see Organization network access policies, Organization filesystem access policies, and Organization MCP access policies.

Found by nightly documentation quality scanner

Dominant language
Markdown
Stars
4.7k
Forks
8.5k
Avg merge
2d 13h
Merged PRs (30d)
139

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from docker/docs

All issues in docker/docs

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.