Use a static site generator as a middleware for the internal help page

Long story short, we now have to maintain 2 different doc pages: /helpand docs.gitlab.com. On docs.gitlab.com we use a hacky script to convert markdown to html using pandoc. Ideally we want to move to an SSG like jekyll or nanoc for docs.gitlab.com, so if we go down that path why not also use the same tool for /help?

Having an SSG would help us build things like having different translations, different versions, etc.

Caveats:

1. On docs.gitlab.com we also host docs for omnibus and the runner.
2. Something else I'm missing...

Relevant issues:

• https://gitlab.com/gitlab-org/gitlab-ce/issues/19996
• https://gitlab.com/gitlab-org/gitlab-ce/issues/19927
• https://gitlab.com/gitlab-org/gitlab-ce/issues?scope=all&sort=id_desc&state=opened&utf8=%E2%9C%93&label_name%5B%5D=help+page&label-name=
• https://gitlab.com/gitlab-com/doc-gitlab-com/issues/35

cc @connorshea @dblessing @virtuacreative @DouweM @rspeicher

mentioned in issue #19996 (closed)

Any chance we could build a script for CI to deploy to different places? meaning, both website and /help?

/help is rendered by the GitLab Rails app itself. There's no CI involved. When a change is merged into master we can trigger a build to start the CI job for docs.gitlab.com.

We wouldn't really need to 'embed' the SSG - just the build result of it (static HTML). That's not hard. However, the bigger problem that I see if that I don't expect that navigation and UI will change when I navigate to a relative URL like /help. If it's a separate subdomain like help.gitlab.example.com it's less shocking.

@dblessing oh dear, subdomains in subdomains.

@connorshea Yes, unfortunately. If we can do it with Pages, that would be ideal. Although, that excludes CE. I don't see a way to do it without causing confusion by embedding a static site at /help.

@dblessing or we could move Pages to CE :P

@connorshea I disagree! We need to keep EE on the top, we need to monetize.

I don't understand why we can't embed a static site at /help. We could normally access via localhost/help, couldn't we? Also, why do we need Pages for that? Isn't it a documentation to be available offline? If so, why do we need Pages? If not, why don't we just point to URL from the /help/ page?

@virtuacreative If we embed an entire site in /help, one of two things will happen:

1. It will replace the entire GitLab UI, including navigation. The look and feel will change and users will be confused why they were directed to a site that looks different than GitLab but is still at the same URL.
2. It will be a sort of frame embedded within the GitLab UI. Navigation from GitLab will remain on the left side and the top bar will be present. Inside the page content area there may be another navigation for the doc site. This will look funny.

Oh, I see. Thanks @dblessing. How software developers normally do with documentation?

@virtuacreative I'd say most web application have a separate doc site. Some applications have built-in docs but rarely do people have both IMO (like we do ).

Thanks @dblessing! Would that be bad if we keep just the website? Meaning, docs will be available online only?

Perhaps for the embed /help we could maintain a summary only, linking to the website.

@virtuacreative Yes, I like that.

Would that be bad if we keep just the website? Meaning, docs will be available online only?

IMO a bad idea, as now each install has the docs for that release embedded and installed. You don't want to version your online docs, and we have git already.

@zj We plan to provide versioned docs on docs.gitlab.com regardless of the future of /help. This is easy because of Git - we check out the stable version and then generate the docs based on that.

Would that be bad if we keep just the website? Meaning, docs will be available online only?

Having docs shipped in /help is I think a good idea. Not every on-premise installation might have internet access. Having docs only at docs.gitlab.com would exclude those people from access to the docs.

Ok, sure. But now the flow would be, go to /help and find an answer. The way this will turn out would be: got to /help, click a link to docs.gitlab.io, think: shit, what version are we running (why would I care as end user?), go a page back, click the link again to locate the version number, and than locate the right version to find the answer.

@dblessing You probably know better than me whats the right way here, but to me this seems cumbersome and weird.

@razer6 Remember that it's the end-user's workstation that needs access to the Internet, not the server. Many organization's servers are restricted from Internet access but I'd say very few workstations are restricted from Internet access - it would make day-to-day work too hard.

@zj I agree. We could generate the link in /help based on the version. When they click the link they will already land on the proper version page. It's a good thing to keep in mind, though.

Once we are re-thinking things and considering changes, perhaps wouldn't be better separating things here? Like, end-user docs-only and admin-docs-only? Think with me.

Case A:

If I'm an end-user, I'm working from my own work station, with internet access most likely, and "I don't care" how the "techy" guys managed to install the GitLab instance that I use for work. So, I don't need access to the installation/admin guides. But I do need access to how-tos, user how-tos: how to create an MR, how to use labels, how to use milestones, how to setup .gitlab-ci.yml, how to create a project, etc. Those are almost "timeless" docs. Multi-version, for sure.

Example: marketing team updating the handbook
My point: they can live in the internet only, accessed from doc.gitlab.com

Case B:

Now, if I'm a maintainer and I'm installing and updating the GitLab instance that my entire company uses, perhaps I don't need to know how to setup projects and stuff within GitLab. But I do need to know how to update it, how to install it, how to enable/disable things. Admin and installing docs are top priority for me. And if I'm installing in my company's intranet (or smt like that), perhaps I won't have internet access in my end. So, yes, for me the docs being available offline, per version, is what matters most to me.

Example: I.T./network/infrastructure folk installing GitLab EE for his company. My point: they can live where they are (only), being accessible offline.

---

What do you all think? Too complicated separate them? Unnecessary? Messy? Terrible idea?

Just brainstorming :)

@virtuacreative terrible

We add another layer of complexity that we cannot/should not afford to. I don't think people really care if user and admin docs are together if there is a good distinction between them, and that's gonna happen 1) with the restructure I've been dealing with, 2) with the new docs site once it's up.

OMG @axil!

Okay, I understand. I thought "terrible" was a possible reaction, indeed

Milestone removed

@dblessing for versioning and design reference we could take a look at the documentation of Sidefx Houdini: https://www.sidefx.com/docs/

Its a program for creating procedural 3d (worked with it in the past) and also holds a lot of programming content. It creates a doc version for each release, plus they apparently updated the styles too recently!

mentioned in issue #20721 (closed)

removed

@dimitrieh I'm not sure the issue you linked is related. We're talking about a GitLab installation's /help page - like GitLab.com/help. This is application help as opposed to the https://about.gitlab.com site.

@dblessing you are right, removed it

Removed moonshots label

This is probably too much work and will be superseded by https://gitlab.com/gitlab-org/gitlab-ce/issues/18739.

closed