cloudflare / cloudflare/cloudflare-docs
improve: Reduce cognitive load and fix logical flow in DNS management docs
- Dominant language
- MDX
- Stars
- 5.2k
- Forks
- 16.7k
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 337
Description
### Proposed changes
https://developers.cloudflare.com/dns/manage-dns-records/
https://developers.cloudflare.com/dns/manage-dns-records/reference/
This feedback addresses the user experience of the "Manage DNS records" documentation, specifically focusing on reducing cognitive load and improving logical flow.
Logical Flow Issues
The "Overview" Gap: The current flow forces users to read theory before performing basic actions.
Fix: Move theoretical links ("Overview", "review DNS records") to a "Before you begin" sidebar or collapsible section. Keep the main flow strictly action-oriented.
Ambiguous "Delete" Action: The instruction "Select Edit. Select Delete" is unclear.
Fix: Explicitly state the UI location (e.g., "Select the three-dot menu next to the record, then select Delete").
Inverted "Originless" Logic: The text provides the solution (100::) before explaining the problem (routing without an origin server).
Fix: Flip the sentence structure: "If you need a placeholder address for Workers... use 100::."
Cognitive Load & Formatting
Visual Clutter: The word "Select" is repeated excessively (5 times in 3 paragraphs), creating visual noise.
Fix: Use imperative verbs without the subject (e.g., "Go to DNS Records," "Click Add record").
Ambiguous Placeholders: The text mentions "Particularly important fields" but doesn't list them before jumping to "Select Save."
Fix: List critical fields (Name, Content, TTL, Proxy) or remove the sentence entirely.
Jargon Spike: Terms like "Originless" and "Reserved IPv6" appear without definition.
Fix: Add plain-English definitions (e.g., "Magic Placeholder").
Proposed Restructuring To improve scannability, I recommend:
Using bullet points for steps instead of paragraphs.
Renaming "Use cases" to "Common Scenarios."
Leading scenarios with the goal (e.g., "Changing your server IP") rather than the technical detail.
### Subject Matter
Critique: Logical Flow and Cognitive Load of DNS Management Docs
### Content Location
This content should be placed as the primary structure for the "Manage DNS records" page. The "Basic Operations" should be converted to a bulleted list near the top, followed by the "Common Scenarios" section.
### Additional information
Revised Snippet Example (Delete Action) Delete a Record:
Go to DNS Records.
Find the record you want to remove.
Click the three-dot menu next to the record.
Select Delete and confirm.
Revised Snippet Example (Changing Server IP) Changing Your Server IP? If your hosting provider changes your IP address:
Update the Content field of your A or AAAA records.
Tip: Check your hosting provider's docs for the new IP.
Revised Snippet Example (Originless) No Server? Use a Placeholder.
If you are using Cloudflare Workers or Redirect Rules but don't have a server yet:
Enter 192.0.2.0 (IPv4) or 100:: (IPv6) in the Content field.
Ensure the Proxy status is set to Proxied (orange cloud).
Contributor guide
Assessment
This issue has not been assessed yet.