[proposal] Merge EE docs into CE docs

We could have two separate index pages, one for CE and one for EE.

Has some shared objectives with #22449 (closed)

docs.gitlab.com/docs

Too redundant

docs.gitlab.com/gitlab

The biggest challenge I see with combining EE and CE docs is merging continually. If a developer is making changes that are specific to EE, they will make doc changes in the EE code-base. How are these changes then incorporated in the combined docs?

Questions:

Do we have the EE docs be the 'source'? Merging CE docs forward as part of the CE-EE merge, and then deploy those docs?
- Downfall: New docs aren't immediately live - have to wait until weekly/next CE-EE merge.
Do we merge EE back to CE? Keep in mind this is opposite direction of the CE-EE merge and may be a bad idea.

docs.gitlab.com/gitlab

That also seems pretty redundant. Why do we need a subdirectory at all?

I agree with @markpundsack. The only reason I can see for /gitlab is if it represents GitLab docs, vs /runner or /omnibus, etc.

Need plan for Runne, Omnibus, and other projects that we'll have.

For omnibus docs I propose having the installation directory which will hold omnibus package, installation from source, docker and so on. This would allow us to remove most of the confusion in where to look for help based on installation method.

@marin

@markpundsack we need the /gitlab subdir for the reasons @dblessing mentioned. We cannot avoid that if we want docs.gitlab.com to serve as a portal with links to various other docs. That's how ansible is doing it btw https://docs.ansible.com/ and https://docs.ansible.com/ansible for the main product and then they host https://docs.ansible.com/ansible-tower/ as well.

@sytses /runner will be on its own subdir.

Mentioned in issue #22701 (closed)

@axil how does this solve merge conflicts? I assume currently merge conflicts are there because someone made an EE feature and merged that into the EE docs. I assume that in the future if we make an EE feature, the merge request (including documentation) still has the EE repo as a target. This will still have the potential for a merge conflict later on.

An alternative (having the docs in a separate merge request from the code) will probably cause docs not to be written.

@axil so runner will be in a subdir /runner but Omnibus will be in an /installation subdir? This is confusing to me.

@sytses

so runner will be in a subdir /runner but Omnibus will be in an /installation subdir? This is confusing to me.

We need to discuss the omnibus case more. I'll open a separate issue. In short, I believe we should start migrating its docs under administration/. The installation/ dir should contain our 3 official installation methods: omnibus, Docker, source. So, the main installation parts will live under installation/ and all additional configuration options under administration/. We have too many docs in Omnibus that also apply to source installations that we can move in the main CE repo.

how does this solve merge conflicts? I assume currently merge conflicts are there because someone made an EE feature and merged that into the EE docs.

That is correct. By having all docs in one repo (CE) will solve the merge conflict issue.

I assume that in the future if we make an EE feature, the merge request (including documentation) still has the EE repo as a target. This will still have the potential for a merge conflict later on. An alternative (having the docs in a separate merge request from the code) will probably cause docs not to be written.

Given the current proposal, we aim for the alternative. I see no other easy way, developers will have to change their mentality and reviewers should be aware of this as well. This is a trade off I'm willing to make, although I can see why others would disagree.

To remind you, @dblessing had opened an issue a year ago (oh my) https://gitlab.com/gitlab-org/gitlab-ce/issues/2916 and you also had commented and we all shared the same concerns.

Mentioned in issue #22449 (closed)

@axil So the proposal in this issue is to separate code changes in the EE and Omnibus repo's from changing the documentation (that will be only in the CE repo). I'm against this since it will be hard to relate the two, this will make it harder for people to contribute, and I'm afraid that the documentation will not always be updated. /cc @dzaporozhets

TLDR; Documentation should stay in the Community Edition, Enterprise Edition, GitLab Shell, GitLab Git, Omnibus, and GitLab Runner repo's.

Changed title: Merge EE docs into CE docs → [proposal] Merge EE docs into CE docs

@sytses Actually, I'm trying to figure out a way for us to not have docs.gitlab.com/ce/ and docs.gitlab.com/ee/ since the majority of the docs are duplicated.

TLDR; Documentation should stay in the Community Edition, Enterprise Edition, GitLab Shell, GitLab Git, Omnibus, and GitLab Runner repo's.

Generally I agree. The overlapping ones are CE, EE and Omnibus.

And as far as Omnibus is concerned, we already mention the Omnibus way in parts of the documentation where we configure various things source/omnibus installations. And this lives in the CE repo. If you take a look at https://docs.gitlab.com/omnibus/ you'll see that we link to docs in CE as well and there is documentation that could also be applied to source installations. Let's talk about this in a separate issue, I'll take a closer look what also applies to source installations that now is only in Omnibus docs.

I'll keep looking for ways to make this easier, thanks for the feedback so far

@axil I agree with @sytses here. Every repo should have own documentation inside even if it is overlapping. If you make a change in one repo its very unlikely you will search and submit doc changes to another.

@dzaporozhets open source contributors are unlikely to contribute to EE compared to CE, though.

Making large changes to the documentation structure causes problems when merging CE into EE and it's not ideal when editing documentation to have to think about what differences EE would have, it's much nicer to do it all in the same file. Overall I think this would be a change worth making.

open source contributors are unlikely to contribute to EE compared to CE, though.

@connorshea I don't talk about community contributions exclusively. Not everyone in GitLab team can follow re-structure changes. When you have only 2-5 people knowing for sure where to put doc changes it can be a problem

Restructure changes is just an example, it won't happen forever :) The main thing is the developer mentality about docs overall and I get it :)

TLDR; Documentation should stay in the Community Edition, Enterprise Edition, GitLab Shell, GitLab Git, Omnibus, and GitLab Runner repo's.

Just an FYI and a reminder to myself, the folks at Docker host all their project's docs under a single repo https://github.com/docker/docker.github.io. They seem to have migrated to a single source of truth recently https://github.com/docker/docker.github.io/blob/d53c6798c9f6b7046ae04277eb4d25ccffc1f0af/README.md.

Why don't we just hide the CE docs and point everyone to the EE docs? For each feature we'll still say whether it's exclusive to a particular EE tier, so that won't change anything.

No one can miss things because they're in the wrong documentation. Search returns only one result for each particular result and it's easier to grok.

Contribution process and such stays exactly the same. CE docs still exist, we just don't expose them on docs.gitlab.com.

I'm OK with not exposing CE docs on docs.gitlab.com as long as they are still in the repository of CE.

mentioned in merge request gitlab-com/gitlab-docs!94 (merged)

@JobV @sytses that's a nice hack :) I submitted a wip MR in https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/94.

A couple of things to consider:

We specifically write "GitLab Enterprise Edition" in various places and that might confuse CE users who will be looking for CE docs. Temporarily fixed with https://gitlab.com/gitlab-com/gitlab-docs/commit/b264728b8cb6554660ed6c3342c51d2044d990e0.
In the footer of each page we have a link that links back to the markdown file if someone wants to contribute. If we only expose EE, that will lead to the EE tracker and contributors will create the MR there. 9/10 we need the MR to happen in CE though. Not sure how to tackle this.
CE>EE merges usually take time which leads to CE docs released first and the EE ones follow after some days. I guess that's something we can live with.

I don't think the wider community will accept EE docs in CE. We solved this with https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/94

closed

Oops, we're working on https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/94/diffs to solve this but the issue title of this issue is wrong so I closed it.

marked this issue as related to #2916 (moved)

marked this issue as related to #18739 (moved)

Now that we only show the EE docs, people use the "Edit page" link if they want to know the source markdown file in order to make a contribution. That leads them to the EE project and they submit MRs there. That leads in missing docs in CE, as we only merge CE>EE and not vice versa. There are at least two cases where that's happened and I realised too late.

We need a combined source for docs.

@axil can't we play with the links meanwhile? Instead of linking to ee-docs, link to ce-docs whenever it exists?

@marcia I thought about that, but then we have docs where we mix CE/EE stuff. Imagine I'm on https://docs.gitlab.com/ee/user/project/issue_board.html#group-level-issue-boards and I find a typo, so I click on the link and I get in CE. But the group boards section is not there :/

There's no easy way to tell.

Ahhh yeah, there's that.

[proposal] Merge EE docs into CE docs

Designs

Child items ...

Activity

Questions:

Admin message

Admin message

[proposal] Merge EE docs into CE docs

Relates to

Activity

Questions: