cloudflare / cloudflare/cloudflare-docs

improve: Reduce cognitive load and fix logical flow in DNS management docs

Open
#30,869 1 comment 0 reactions 0 assignees View on GitHub
content:new documentation product:dns stale
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.