Proposal: Merge the CE and EE docs
The problem
We currently maintain two sets of docs: one in the gitlab-ce repo and one in gitlab-ee. They are similar, and some pages are identical, but they are different. Each set is published to our site, while also packaged with its respective version of GitLab (CE vs EE) and displayed under /help (which we plan to remove, in favor of exclusively hosting docs on our site).
See examples of:
While docs.gitlab.com now 'hides' the /ce path by preventing indexing and avoiding links to it, this only resolved some user confusion; it does not solve the problem that developers and technical writers frequently need to resolve conflicts between the two copies of the doc and the docs are generally more difficult to update.
Potential solutions
Here are two options, in order to ensure a good experience by CE users, while mitigating the current problem:
- Merge both sets, and build the docs from a single codebase (CE)*. Ensure that each doc and subsection specifies the tiers it applies to.
- Build the docs from two codebases, yet keep them nearly identical (more so than today): we'll only differ the docs that pertain to features that are completely non-existent in CE, or where the majority of features (covered in the doc) are unavailable in CE. Note: This option would be difficult to maintain if the linked proposal to merge the CE and EE codebase occurs as described. In that case, we may instead need a single doc path, and a rake task that's capable of making the EE docs 'CE ready'.
Either way, we can further improve the user experience by:
- Producing a new set of icons to place next to links, inline, when we link to an individual feature that's only available in some tiers, indicating availability. These could be hidden based on the user's tier selection.
- Including front-matter metadata that indicates whether the page contains EE-only features, so that we can have a search option to exclude them.
Needs
- A diff of the docs (CE to EE) to determine how much work is involved in merging them => https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21089
- A process to bring both sets of docs into alignment, while ensuring that all features are properly labeled with tiers. We can cross-check against features.yml. Can be done one path at a time, with work shared among the tech writers. (See further notes in TW weekly agenda > 2018-08-08)
- Confirmation that the license of the docs is acceptable. I believe this was changed to CC-BY-SA but I am not sure why.
- Plan for the API, for example, leave API content alone while working on a new Open API spec-based system that can differentiate CE and EE (see further notes in TW weekly agenda > 2018-08-08)
Important Background
This was previously discussed here https://gitlab.com/gitlab-org/gitlab-ce/issues/22617 however, this was before https://gitlab.com/gitlab-org/gitlab-ee/issues/2952 in which the decision was made to attempt to move to a single codebase. There were efforts made to isolate EE-specific code in preparation for this change. DZ suggested we make the CE repo read-only and generate it by running a rake task that removes EE code. People would be recommended to create issues and merge requests to the EE repo. The conversation culminated in a draft blog post by Sid in order to discuss this with the community, but I believe it was not posted and there has been no further progress. Since that conversation, Axil created this https://gitlab.com/gitlab-org/gitlab-ce/issues/46476 but it doesn't cover everything we need to discuss and consider, so I've created this new issue.
* Note: If the above suggestion by DZ occurs, we may need to switch the 'editable' set of docs to being stored in EE; this would either happen at the same time as the rest of the codebase does this, or we can do this right off the bat (in advance of the rest of the codebase), given that the docs have a separate license in CE and EE vs the rest of the code.