Documentation and External Resource Links

    March 9, 2025
    + 12

    All links in the UI should provide sufficient context for the user, so they know where they will go after they click a link.

    It should never be a surprise where a user goes after they click a link in the UI.

    The issue of documentation links will still need to be revisited at a future date.

    To link out to documentation from inside the UI:

    • Do not just link directly to the documentation with no context. Add some introductory information to get the user started. For example, A bucket contains scopes and collections.

    • Invite the user to Learn More.

    • Set the actual blue link text to Learn More.

    • Use an external link icon at the end of Learn More to show that the user will navigate out of the UI.

    • Do not put a period at the end of Learn More.

    If you want to link to another external resource:

    • Do not just link directly to the resource with no context. Add some introductory information to get the user started. For example, Use a JavaScript function to define a file filter.

    • Set the actual blue link text to the name of the resource.

    • Add an external link icon at the end of the link text to show that the user will navigate out of the UI.

    • Do not put a period at the end of the link text.