Docker Engine Networking updates for style, clarity#24322
Docker Engine Networking updates for style, clarity#24322akristen wants to merge 2 commits intodocker:mainfrom
Conversation
…y, add bridge network section with existing info, add some context to unspool concepts
akristen
added
area/engine
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![docker-agent[bot]](https://avatars.githubusercontent.com/in/2787757?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review Summary
Assessment: 🟡 NEEDS ATTENTION
This PR restructures the Docker Engine networking overview page to improve clarity. While the content improvements are valuable, there are critical Markdown formatting issues that must be fixed before merging:
Critical Issues (HIGH)
- Code block indentation error - The console code block is indented with 4 spaces, which will break rendering in Hugo/Markdown
Notable Issues (MEDIUM)
- Grammar errors - Missing articles ("a" and "the") make the text grammatically incorrect
About This Review
This automated review focuses on documentation quality, style guide compliance, and technical accuracy. All findings have been verified against the changed code.
| If you want to test the bridge network, you can send a ping request | ||
| from an active container and wait for the reply. For example: | ||
|
|
||
| ```console |
There was a problem hiding this comment.
CRITICAL: Code block indentation error
The code block is indented with 4 spaces before the triple backticks:
```console
$ docker run --rm -ti busybox ping -c1 docker.com
...
```
This is incorrect Markdown formatting that will likely break rendering. Code blocks should start at column 0 (not indented) unless they're inside a list item.
Fix: Remove the 4-space indentation:
```console
$ docker run --rm -ti busybox ping -c1 docker.com
...
<!-- cagent-review -->
|
|
||
| When Docker Engine starts for the first time, it uses a single | ||
| built-in network called the default bridge network. This means that when | ||
| you start container without specifying `--network` option, the container |
There was a problem hiding this comment.
Grammar error: Missing articles
The sentence is missing two articles:
- "you start container" → "you start a container"
- "without specifying
--networkoption" → "without specifying the--networkoption"
Current:
you start container without specifying
--networkoption, the container
Should be:
you start a container without specifying the
--networkoption, the container
Per STYLE.md, use articles for clarity and grammatical correctness.
| When Docker Engine starts for the first time, it uses a single | ||
| built-in network called the default bridge network. This means that when | ||
| you start container without specifying `--network` option, the container | ||
| defaults to the `bridge` value. When your Docker host (the virtual or physical | ||
| machine running Docker) has Internet access, no additional configuration is | ||
| needed for the container to have Internet access. |
There was a problem hiding this comment.
The engine doesn't really "use" a network; the default bridge network is created and containers you run automatically attach to it.
This paragraph combines two unrelated things: the fact that there is a default network, and the fact that containers can access the internet. (I am not sure why it is/was written as if this is unique to the default bridge network; it's true for any bridge network.)
There was a problem hiding this comment.
How about this:
When Docker Engine starts for the first time, the default bridge network is created and containers attach to it automatically. The Docker bridge network is an isolated network for containers to communicate
with each other. Containers
default to thebridgevalue if no othernetwork_modeoption is specified.
I've omitted/removed the sentence about internet access since i think it's redundant, but can add it back if you think it's necessary to say~ :) what do you think?
| * By default, the bridge network gives your containers | ||
| access to external networks through masquerading, or borrowing your Docker | ||
| host's public IP address to make and receive requests from the Internet. | ||
| * While your containers communicate on the bridge network, devices |
There was a problem hiding this comment.
Containers on the default network do not communicate with each other. Containers on custom bridge networks do.
There was a problem hiding this comment.
I'm a little confused... The original doc says this:
When Docker Engine on Linux starts for the first time, it has a single built-in network called the "default bridge" network. When you run a container without the --network option, it is connected to the default bridge.
Which made me think that bridge == default, or that it's interchangeable (or that dockerd defaults to bridge?) But you have to manually change it for custom networks or to use the host network.
What would be the default network if it isn't bridge (per the original doc)? Is it the host, or something else called literally "default"?
Co-authored-by: Alexa Kristensen <81787716+akristen@users.noreply.github.com> Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
| The Docker bridge network is an isolated network for containers to communicate | ||
| with each other. | ||
|
|
||
| * By default, the bridge network gives your containers |
There was a problem hiding this comment.
@dvdksn is this content still good to keep / is accurate?
There was a problem hiding this comment.
(minus the 'by default' sentence that ive removed)
| machine running Docker) has Internet access, no additional configuration is | ||
| needed for the container to have Internet access. | ||
|
|
||
| The Docker bridge network is an isolated network for containers to communicate |
There was a problem hiding this comment.
| The Docker bridge network is an isolated network for containers to communicate |
2 participants
This PR:
I didn't add any edits to other sections, but may do some additional style edits if time permits. Otherwise, may just send this change out for now and revisit the rest of the content later. :)
I think I explained how the bridge network functions as I understand it, but will definitely need some validation around the particulars with a review. 😅