How Custom Guide Links Are Finally Clicking Through

Create a seamless path - the sudden rise of user-created custom guides in Grafana demands more than just linking. We're moving past "here's a link" to directing teams straight to exactly what they need.

Understanding the shift The old ?doc= system was brilliant for standard guides but left custom Pathfinder guides floating in an invisible corridor. Now, thanks to ?doc=api:<resourceName>, we’re closing that door. This isn’t just technical - it’s cultural. When ordinary users can share these guides with one click, we’re turning documentation into a collaboration engine.

• Readability reigns - the api: prefix keeps URLs human-friendly.
• Security stays intact - backend details aren’t spilling into the wild.
• Discoverability improves - guides surface via sidebar, not buried pages.

The psychology of clicks People don’t know this exists until they’re frustrated. Enter the "I wish this worked!" moment that grows into trust. Here is the deal: clarity in the URL means clarity in purpose. Users know exactly what’s coming next.

Unseen layers

• Custom guides persist if published - drafts get flagged.
• Resource names auto-generate but stay private.
• Unpublished guides trigger errors before they reach users.

The debate Critics say this adds complexity. But the alternative - users mapping through external docs - is messy. Do we keep adding steps? But there is a catch: simplicity wins here.

The Big Takeaway Custom guides should never feel like a dark web link. They should just work. As we integrate this, ask: Is this guide truly accessible or just technically supported?

TITLE ensures the strategy stays sharp and focused.

Deep links make magic real. Now, how do we keep that momentum? Always test edge cases. Always listen to users. The future builds on today’s invisible wires.