Docker Engine Networking updates for style, clarity#24322
Docker Engine Networking updates for style, clarity#24322akristen wants to merge 1 commit 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.
|
|
||
| * 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. |
There was a problem hiding this comment.
| host's public IP address to make and receive requests from the Internet. | |
| host's public IP address to make requests to and receive replies from the Internet. |
| * 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.
| * While your containers communicate on the bridge network, devices | |
| * While your containers communicate with each other on the bridge network, devices |
| 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.)
| 1 packets transmitted, 1 packets received, 0% packet loss | ||
| round-trip min/avg/max = 6.564/6.564/6.564 ms | ||
| ``` | ||
| ## Bridge network |
There was a problem hiding this comment.
I guess this section is not meant to explain bridge networks in general, but the default network
| ## Bridge network | |
| ## Default network |
| * 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.
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. 😅