[meta] Docs plan

Restructuring the documentation from the ground up. A multi-step process that will help the growth of our documentation. Many of the steps are radical, this won't happen overnight. Each step will have its own discussion.

What this is about

In the end this is all about docs.gitlab.com and the need to convert it into a portal hosting all our documentation and guides. This is challenging because of the current deploy process and the many repos we need to build docs from.

It will have the same layout (header/footer) as about.gitlab.com, built with a static site generator (nanoc).

And of course we should claim a position in https://github.com/PharkMillups/beautiful-docs when this plan is finally implemented.

Architecture plan

• Root website: docs.gitlab.com that will server as a portal.
• Main GitLab documentation : docs.gitlab.com/{ce,ee}/
• Runner documentation : docs.gitlab.com/gitlab-runner/ or docs.gitlab.com/runner
• Omnibus documentation: docs.gitlab.com/omnibus/

Steps

Must

1. DONE Merge University to CE https://gitlab.com/gitlab-org/gitlab-ce/issues/22449

2. IN PROGRESS Serve docs.gitlab.com with Pages https://gitlab.com/gitlab-com/doc-gitlab-com/merge_requests/25

3. IN PROGRESS CE/EE Documentation restructure https://gitlab.com/gitlab-org/gitlab-ce/issues/3349

4. ABORTED Merge EE to CE docs https://gitlab.com/gitlab-org/gitlab-ce/issues/22617

5. Remove built-in help https://gitlab.com/gitlab-org/gitlab-ce/issues/18739

Should

1. Versioned documentation

2. Add GitHost.io to docs https://gitlab.com/gitlab-com/doc-gitlab-com/issues/60

3. Add GitLab Runner to docs https://gitlab.com/gitlab-com/doc-gitlab-com/issues/47

4. OpenAPI docs

Good to have

1. Switch to LFS for university images

2. Switch to Algolia search engine https://gitlab.com/gitlab-com/doc-gitlab-com/issues/73

@axil Let me start by saying my knowledge about such things is minimal at best so the following remarks may be quite wrong and I may have even misunderstood the problem! However, it seems to me that the challenge faced by the deploy process could be solved by having the docs respective products' repos CD look after moving their documentation to the right place.

i.e. The gitlab repo would look after the process (as far as it can) for it's docs. When a change for the repo is pushed and successfully merged, then the CD for that repo finishes by pushing its docs to the required location in docs-gitlab-com (e.g. content/gitlab) repo. Thus docs-gitlab-com could act just as any other repo really; doc changes get pushed to it and that causes a new build.

In short the product repo deploys its doc files to the doc repo which triggers a doc rebuild.

I'm not sure we need a large meta-issue plan for this. Can't we just have a documentation tag w/ these broken up into small issue? If we broke it down into small, more easily doable issues, this wouldn't feel like a moonshot.

The stuff under steps is great. Those are the smaller issues we are work on and not make something bigger out of it than it needs to be. My recommendation is to delete this giant meta issue and work on the issues described in the steps.

cc @axil @SeanPackham @sytses we can talk through this in today's meeting.

Changed title: [meta] Docs 2.0 → [meta] Docs plan

Removed moonshots label

closed