TL;DR: Docs need IP addresses that teach the format without pointing readers at a live network or at your office. Generate a candidate, reject private and reserved ranges unless the paragraph is about those ranges, and mark the value as an example in the same sentence. A bare quad in a public page will be copied by someone in a hurry. Draw candidates from the random IP generator, then keep the one your paragraph can defend.
The API guide that became a probe list
A payments startup published a guide to their webhook logs. The sample source address was a generator result the writer liked because it “looked realistic.” Support noticed, weeks later, that the address belonged to a regional library and that a handful of readers had been hitting it with the sample curl command from the guide, with the library’s address left in the –resolve or the URL host by mistake. The curl was not clever malware. It was a copy-paste from a doc that had not said “this host is fictional and not reachable.” The library’s admin was polite and tired. The startup pushed a revision the same day using an address from the documentation range and a sentence that said the host must not be contacted.
Pick the range to match the sentence
If the sentence is “a public client might look like this,” you still do not need a live public client. The ranges 192.0.2.0/24, 198.51.100.0/24, and 203.0.113.0/24 exist so documentation can look like IPv4 without assigning a victim. If your generator does not target those ranges, generate and then replace. Vanity realism is how the library got into the guide. If the sentence is “a packet from a private LAN,” use 192.168.0.0/16 or 10.0.0.0/8 on purpose and say you did. A random public-looking address in a LAN example teaches two lessons, one of them wrong.
- Public-shaped example: documentation range, labeled example.
- LAN example: a private range, labeled as private.
- Failure example: something obviously invalid, such as an octet over 255, if you are teaching validation.
- Your real gateway: not in the public doc, even if it is convenient.
One address, one job
Do not reuse a single generated address for the attacker, the customer, and the server in the same diagram. Readers will think those roles are the same host. Generate three, or take three documentation hosts (.10, .20, .30) and assign roles in a caption. Keep the caption next to the figure. A number in an image with no caption will be OCRed into someone’s terminal.
Changelog entries and test fixtures have the same duty. A fixture called attacker_ip that escapes into a production config through a sloppy import is a self-inflicted blocklist. Name the fixture synthetic_attacker_ip. Make the production loader refuse that prefix. The generator cannot save you from a later copy. The name can.
Screenshots age worse than text
A screenshot of a generator page includes whatever else was on screen and becomes stale the next time you click. Crop to the address, or type the address into the doc as text so you can change it without a new capture. Text can be searched when you need to retract it. A PNG of a blog cannot. The payments guide’s second mistake was a screenshot that still circulated in a cached social preview after the HTML was fixed.
Review like someone will paste it
Before you publish, assume a stranger will paste the address into a ping command. If that thought makes you uncomfortable, the address does not belong in the page. Swap in a documentation address. Add the word example. Read the paragraph aloud and see whether it instructs a contact or describes a shape. Description is the goal. Contact is the accident.
Internal runbooks can be slightly looser if they stay on a wiki with access control, and they should still avoid customers’ real addresses. “Internal” files leak. Synthetic from the start is cheaper than a scrub after a leak. Generate, filter, label, and move on.
Translations and mirrors copy your mistake
Once a live address ships in a guide, translations, scraped blogs, and a PDF export will keep it after you fix the HTML. Prefer a documentation-range address the first time so the mirrors are dull. If you already shipped a bad one, change the page, add a one-line correction at the top, and do not assume the social preview updated. The payments startup’s cached preview kept sending readers to the old image. A second commit to the HTML did not reach them.
Leave the reader nothing to dial
The library did not volunteer to be a sample. Your next guide can use a number that the internet has already agreed is for books and slides. Generate if you need a starting point, then prefer the documentation range in anything the public will read. The curl command in the wild should fail closed because the name was never real, not because a stranger’s firewall got lucky.