Questions/considerations about cross-linking docs and university

Based on support team call from May 13.

Stan mentioned that University and Docs should cross-link as they as complimentary. This makes perfect sense - at least when considering university.gitlab.com and docs.gitlab.com. However, we also have the same help documentation in each on-premises GitLab instance at /help. We're constantly struggling with how to improve the docs experience but are held back or are unable to make these improvements for both /help and docs.gitlab.com. Based on this, here's a few questions/thoughts:

1. Does it still make sense to ship docs in /help?
2. University and (soon) Docs can be deployed in GitLab Pages. Instead of shipping docs at /help maybe we can ship both as OOTB Pages sites that dynamically build cross-links to each other rather than university.gitlab.com and docs.gitlab.com. This would allow us to refine the experience of both without worrying about differences in how they're deployed.

cc/ @stanhu @cabargas @balameb

@dblessing I know /help is based off of the doc dir in GitLab CE; isn't this where docs.gitlab.com is from too? Or do they live in different repositories?

@stanhu yes that's correct. They're both from the same source. Currently we have weird linking paths. For example, something in the UI may link to /help but then docs themselves might link out to docs.gitlab.com or in the future to university. And navigation in /help is subpar. There are lots of strange issues like this.

Isn't there only one case where /help links to docs?

$ git grep docs.gitlab.com
administration/high_availability/gitlab.md:  [Nginx documentation](http://docs.gitlab.com/omnibus/settings/nginx.html#enable-https)

I'd be hesitant to remove the /help link from GitLab, since having a local help page without having to depend on GitLab.com is a plus. Maybe @axil has an opinion here.

What kinds of issues are you running into with navigation?

I'm all in favor of using GitLab Pages to deploy both docs.gitlab.com and university.gitlab.com.

FWIW, we do use GitLab Pages to deploy university.gitlab.com

An important complementary observation is that having GitLab links cause end users to request support on GitLab and not on their on-premise instance. We should look into clreaing this out as well.

Does it still make sense to ship docs in /help?

Yeah, I would be against removing them, based on @stanhu's observation about having a local help page without having to depend on GitLab.com or docs.gitlab.com. And I'm pretty sure Dmitriy, Job and Sytse would disapprove

For example, something in the UI may link to /help but then docs themselves might link out to docs.gitlab.com or in the future to university.

The only time that docs should point outside is when referring to a doc in EE if we are browsing /help of a CE instance and vice versa, as well as when pointing to Omnibus or Runner docs.

And navigation in /help is subpar.

That is unfortunately the case :/ I'm hoping at some point that we can change our Markdown engine to something more powerful (kramdown) which is the one we can also use in Middleman (already used on the main website), and that's what we plan to use on docs.gitlab.com.

That would help us do fancy stuff and rearrange things in the /help page, with adding more CSS classes to certain parts.

Isn't there only one case where /help links to docs?

@stanhu pull again, I recently submitted an MR to change doc to docs now that we enabled the redirect.

What kinds of issues are you running into with navigation?

Right now there is no concrete structure and some links are buried deep down other links. For example https://gitlab.com/gitlab-org/gitlab-ee/issues/145.

mentioned in issue #41 (closed)