Skip to content

Context-specific help for GitLab

Problem to solve

When browsing projects on an arbitrary GitLab instance, people may come across things they are unfamiliar with - a random example being Issue Boards https://gitlab.com/gitlab-org/gitlab-ce/-/boards?milestone_title=10.0

While some elements here provide explanations for what they represent or what their purpose might be, either via dialogs or popups, let's assume that the purpose of the "Boards" in general remains a mystery to the user.

One can turn to the Help, and there is a "?" icon in the upper right of the screen. It opens a drop-down menu, but choosing the most promising entry there, Help, takes you to the main help page https://gitlab.com/help and that's it. From there, you have to find your way to whatever you are looking for yourself.

Intended users

Everyone who wants a quick answer to "Where am I, what is its purpose and and what can I do here?"

Further details

Proposal

There could a a context-specific help entry, which takes the user to a suitable help page for the current context.

For the example of Issue Boards, this could be https://gitlab.com/help/user/project/issues/index.md#issue-boards or the more detailed https://gitlab.com/help/user/project/issue_board.md (I'd prefer the latter).

Permissions and Security

I'm not aware of any special permissions required to view help pages. If there are for some projects, then it might be necessary to show of hide the context specific help entry depending on the user's privileges.

Documentation

Some sort of mapping of "we're here, this is the associated help page" has to be created. If there are multiple equally suitable pages, then new landing pages might have to be created, there those will be listed.

Testing

Tests like "Does everything in GitLab have a help page?" would have to be created.

What does success look like, and how can we measure that?

A new context-specific entry in the help menu is available, and when clicked, this takes the user to a help page suitable for the page where they clicked the menu entry.

Links / references