TL;DR: Random addresses are fine for throwaway mocks. Public documentation should prefer IETF documentation ranges such as 192.0.2.0/24 so readers are not invited to contact a stranger. Generate samples with the random IP tool for labs; label documentation ranges explicitly in README files.
The README that DDoS’d a stranger’s feelings
An open-source project used a “realistic” address from a generator in a quickstart. Curious readers pasted it into scanners. The address belonged to a real network that started receiving odd probes. Nobody meant harm. The example still created work for an abuse desk. Documentation ranges exist to prevent that genre of oops.
Maintainers deleted the address from main branch within hours, but search indexes and forked tutorials kept copying it for months. The lesson is not “never use examples”—it is “publish examples that the internet agrees are non-routable fiction.” Random draws skip that agreement unless you filter them.
What documentation ranges are for
Blocks like 192.0.2.0/24, 198.51.100.0/24, and 203.0.113.0/24 (TEST-NET) are reserved for examples and documentation. They are not for production routing on the public internet. When readers see them with a caption—“example only”—they learn the shape of an IP without gaining a target.
- Docs and blog posts: prefer TEST-NET and say so in prose.
- Private diagrams: 10.0.0.0/8 and 192.168.0.0/16 are fine when labeled private.
- Fuzzing local validators: random batches are convenient inside CI on loopback.
- IPv6 docs: use 2001:db8::/32 for the same reason v4 has TEST-NET.
RFC 5737 and related documents spell out the v4 ranges; teach contributors where to look so code review can cite a norm instead of vibes. New hires from app development backgrounds often know private RFC1918 space but not TEST-NET—add a one-paragraph primer to CONTRIBUTING.md.
Where random still wins
Unit tests that need hundreds of distinct strings, UI demos that must not look identical every screenshot, and classroom drills about parsing all benefit from variety. Keep those outputs inside the lab or the test runner. Do not promote them as “safe public examples” without a human pass for reserved, documentation, and multicast space.
Property-based testing libraries shine with random inputs constrained by custom generators. You might generate random hosts while excluding bogon lists your product rejects. That is engineering use, not tutorial use. Export only the shrunk failing case when you file a bug—often a single neat address after minimization.
A simple editorial rule
If the address will be crawled by search engines in a tutorial, use a documentation range. If the address will die with the test process, random is acceptable. If you are unsure, use documentation ranges. You can still visit the generator when you need variety for an offline worksheet—just rewrite the final published samples.
Automating the guardrail in repos
Teams add linters that fail CI when pull requests introduce dotted quads outside allowlists in markdown and YAML. A common pattern: permit TEST-NET, RFC1918, and localhost; flag everything else in docs/ unless a maintainer override comment appears. Random generators in local dev stay unrestricted; the linter watches what ships.
Pre-commit hooks that scan for `\d{1,3}(\.\d{1,3}){3}` produce false positives on version numbers—tune regex or scope to known config keys like `allowed_ips:`. The goal is not perfection; it is stopping the obvious copy-paste of 8.8.8.8-style literals where 203.0.113.53 belongs.
Teaching students the difference
Computer networking classes need realistic-looking strings to teach subnetting. Use documentation space for homework published online. For in-class-only packets on isolated labs, random or private space is fine. Syllabus language should mirror the classroom story from our generator page: inventing an address is not permission to probe the public internet.
When students ask “can this IP be real?”, teach them to check allocation registries and special-purpose registries—not to ping and see. Ethical framing lands better alongside technical rules than as an afterthought lecture.
Pair tools without mixing jobs
Use the generator when you are drafting volume and variety. Replace with TEST-NET before you merge to main. Use the real IP lookup only when the sentence is about your live connection. Three different jobs; three different kinds of numbers.
Technical writers can keep a snippet library: “example client v4,” “example server v4,” “example v6,” each pinned to documentation prefixes. Developers pull from the library instead of rolling dice at publish time. Random tools remain the fast sketchpad; the library is the shipping crate.
When maintainers inherit bad examples
Forked repos copy addresses forward for years. During your first audit of a legacy tutorial, search for dotted quads and replace stragglers with 203.0.113.x even if the old line “worked” in demos. Changelog entries that say “docs: move to TEST-NET” signal downstream packagers to refresh their mirrors. Small hygiene prevents the next intern from running nmap against a clinic because a wiki still showed a catchy address.
Package managers that embed default config YAML deserve the same audit. A single “example upstream” line in Helm values travels farther than a blog post because operators apply it without reading prose. Pin examples to documentation space in values.schema.json descriptions so IDEs surface the hint while people type.
