Guidance on writing/style of “View documentation” links

Description

As described at https://gitlab.com/gitlab-org/gitlab-ce/issues/30495, to direct users to Help we currently use a mix of: “View documentation”, a ? icon, or “About X”.

We have to be more consistent and standardize this. There may be more than one solution, but the options need to be backed by some rationale so that we can apply it consistently.

Proposal

Inspired from Windows Design Guidelines for Help.

In order of preference:

1. If the most relevant information can be summarized succinctly, put the summary directly in the UI instead of using a Help link. However, you can use a Help link to provide supplemental information.
   • Example: “User cohorts show how active users are in the last 12 months. More information”
2. If it's not possible to provide relevant information succinctly, phrase Help link text in terms of the primary question answered by the Help content. Don't use "Learn more about," "Tell me more about," or "Get help with this" phrasing. Phrase Help links to clearly indicate assistance and predict the results of the link. Help links should never read like action links like “Open documentation”. As an exception, you can use "More information" to supplement instructions that are directly in the UI, especially if providing specific information in the Help link leads to unnecessary repetition or makes the link less compelling.
   • Example: “What are user cohorts?”
3. If there isn't space available for a Help link text, use a circle question mark icon (?) linked to the Help content, with a tooltip phrased in terms of the primary question answered by the Help content.
   • https://ux.stackexchange.com/questions/64920/info-icon-vs-question-mark
   • https://ux.stackexchange.com/questions/80954/is-the-question-mark-internationally-recognised-as-an-icon-for-help
   • https://ux.stackexchange.com/questions/101133/is-it-better-to-use-i-or-for-tooltip-help-content-on-mobile

Exception: If the Help content is outside of the GitLab instance (e.g. content at about.gitlab.com), make that clear in the link text. Doing so helps make the result of the links predictable.

• Example: “For more integrations, go to GitLab’s website”

According to this article by Nielsen Norman, “Learn more” links have poor information scent and are bad for accessibility. Users tend to ignore them. More descriptive labels help users confidently predict what the action/next page will be.

Links / references

• https://www.nngroup.com/articles/learn-more-links/
• https://msdn.microsoft.com/en-us/library/windows/desktop/dn742494(v=vs.85).aspx