Ship the docs site with GitLab
What we need to solve
The difference of styles between /help
and docs.gitlab.com makes the work on the docs site much more complicated and truncated. It doesn't allow us to do anything special to the docs because it doesn't render or render weirdly in /help
.
- Once we change the markdown engine to Kramdown, there will be quite some noise in markdown files rendered with GFM, making them little more confusing for reading through
/help
-
/help
doesn't have breadcrumbs or any kind of docs navigation - We're willing to get rid of
/help
, but, instead, I'm proposing to build the docs site with GitLab, the application.
/help
Advantages of maintaining -
/help
is helpful for self-managed instances without access to the internet. If we just remove it, we'll make their lives a lot more complicated - By maintaining
/help
we have up-to-date versioned docs for GitLab.com in gitlab.com/help - We won't need to refactor the whole
app/views
files in CE/EE (i.e. the question-mark links out to /help pages) as we would if we just removed of/help
How to solve all the problems
Maintaining /help
but making it look exactly like docs.gitlab.com.
- Ship and build gitlab-docs with CE and EE
- Add a configuration in GitLab to make it optional (something like
docs: true
ordocs: false
) - Locally, render on
/help
the same as we see inlocalhost:3000
when we runbundle exec nanoc live
- Keep the relative links in the docs and in
app/views
- Only use pull paths for Runner and Omnibus, as we currently do
Implementation
- Pull gitlab-docs into CE/EE
- Once we start GitLab, make it build the docs site (
nanoc compile
) - Serve the docs site under
your-instance/help
- I asked a few devs during the summit if this would be a great deal of work and they all said that it would probably be doable, no biggie.
References
- Getting rid of
/help
: https://gitlab.com/gitlab-org/gitlab-ce/issues/18739 - UX recently discussing this: https://gitlab.com/gitlab-org/gitlab-ce/issues/34005
- Similar (old) proposals: https://gitlab.com/gitlab-com/gitlab-docs/issues/53, https://gitlab.com/gitlab-org/gitlab-ce/issues/20068, https://gitlab.com/gitlab-org/gitlab-ce/issues/32514, https://gitlab.com/gitlab-org/gitlab-ce/issues/34673
- General complains and requests: https://gitlab.com/gitlab-org/gitlab-ee/issues/2297, https://gitlab.com/gitlab-org/gitlab-ce/issues/42142, https://gitlab.com/gitlab-org/gitlab-ce/issues/44433, https://gitlab.com/gitlab-org/gitlab-ce/issues/29898, https://gitlab.com/gitlab-org/gitlab-ce/issues/46394, https://gitlab.com/gitlab-org/gitlab-ce/issues/50768, https://gitlab.com/gitlab-org/gitlab-ce/issues/3869
Preview
Just to give an idea about what I'm thinking, this is more or less how I picture it:
BEFORE | AFTER |
---|---|
Edited by Mike Lewis