Document docs.gitlab.com monthly release process

Mostly port content from the gitlab-docs project
and streamline the monthly release process.

doc/development/documentation/site_architecture/index.md

@@ -4,14 +4,16 @@ description: "Learn how GitLab's documentation website is architectured."
 
 # Documentation site architecture
 
-Learn how we build and architecture [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs)
-and deploy it to <https://docs.gitlab.com>.
+The [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) project hosts
+the repository which is used to generate the GitLab documentation website and
+is deployed to <https://docs.gitlab.com>. It uses the [Nanoc](http://nanoc.ws)
+static site generator.
 
-## Repository
+## Architecture
 
 While the source of the documentation content is stored in GitLab's respective product
-repositories, the source that is used to build the documentation site _from that content_
-is located at <https://gitlab.com/gitlab-org/gitlab-docs>.
+repositories, the source that is used to build the documentation
+site _from that content_ is located at <https://gitlab.com/gitlab-org/gitlab-docs>.
 
 The following diagram illustrates the relationship between the repositories
 from where content is sourced, the `gitlab-docs` project, and the published output.
@@ -43,8 +45,23 @@ from where content is sourced, the `gitlab-docs` project, and the published outp
     G --> L
 ```
 
-See the [README there](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md)
-for detailed information.
+You will not find any GitLab docs content in the `gitlab-docs` repository.
+All documentation files are hosted in the respective repository of each
+product, and all together are pulled to generate the docs website:
+
+- [GitLab](https://gitlab.com/gitlab-org/gitlab/tree/master/doc)
+- [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc)
+- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs)
+- [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc)
+
+NOTE: **Note:**
+In September 2019, we [moved towards a single codebase](https://gitlab.com/gitlab-org/gitlab-ee/issues/2952),
+as such the docs for CE and EE are now identical. For historical reasons and
+in order not to break any existing links throughout the internet, we still
+maintain the CE docs (`https://docs.gitlab.com/ce/`), although it is hidden
+from the website, and is now a symlink to the EE docs. When
+[Pages supports redirects](https://gitlab.com/gitlab-org/gitlab-pages/issues/24),
+we will be able to remove this completely.
 
 ## Assets
 
@@ -73,28 +90,112 @@ Read through [the global navigation documentation](global_nav.md) to understand:
 - How the global navigation is built.
 - How to add new navigation items.
 
-## Deployment
+<!--
+## Helpers
 
-The docs site is deployed to production with GitLab Pages, and previewed in
-merge requests with Review Apps.
+TBA
+-->
 
-The deployment aspects will be soon transferred from the [original document](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md)
-to this page.
+## Using YAML data files
 
-<!--
-## Repositories
+The easiest way to achieve something similar to
+[Jekyll's data files](https://jekyllrb.com/docs/datafiles/) in Nanoc is by
+using the [`@items`](https://nanoc.ws/doc/reference/variables/#items-and-layouts)
+variable.
 
-TBA
+The data file must be placed inside the `content/` directory and then it can
+be referenced in an ERB template.
 
-## Search engine
+Suppose we have the `content/_data/versions.yaml` file with the content:
 
-TBA
+```yaml
+versions:
+- 10.6
+- 10.5
+- 10.4
+```
 
-## Versions
+We can then loop over the `versions` array with something like:
 
-TBA
+```erb
+<% @items['/_data/versions.yaml'][:versions].each do | version | %>
 
-## Helpers
+<h3><%= version %></h3>
 
-TBA
--->
+<% end &>
+```
+
+Note that the data file must have the `yaml` extension (not `yml`) and that
+we reference the array with a symbol (`:versions`).
+
+## Bumping versions of CSS and Javascript
+
+Whenever the custom CSS and Javascript files under `content/assets/` change,
+make sure to bump their version in the frontmatter. This method guarantees that
+your changes will take effect by clearing the cache of previous files.
+
+Always use Nanoc's way of including those files, do not hardcode them in the
+layouts. For example use:
+
+```erb
+<script async type="application/javascript" src="<%= @items['/assets/javascripts/badges.*'].path %>"></script>
+
+<link rel="stylesheet" href="<%= @items['/assets/stylesheets/toc.*'].path %>">
+```
+
+The links pointing to the files should be similar to:
+
+```erb
+<%= @items['/path/to/assets/file.*'].path %>
+```
+
+Nanoc will then build and render those links correctly according with what's
+defined in [`Rules`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/Rules).
+
+## Linking to source files
+
+A helper called [`edit_on_gitlab`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/lib/helpers/edit_on_gitlab.rb) can be used
+to link to a page's source file. We can link to both the simple editor and the
+web IDE. Here's how you can use it in a Nanoc layout:
+
+- Default editor: `<a href="<%= edit_on_gitlab(@item, editor: :simple) %>">Simple editor</a>`
+- Web IDE: `<a href="<%= edit_on_gitlab(@item, editor: :webide) %>">Web IDE</a>`
+
+If you don't specify `editor:`, the simple one is used by default.
+
+## Algolia search engine
+
+The docs site uses [Algolia docsearch](https://community.algolia.com/docsearch/)
+for its search function. This is how it works:
+
+1. GitLab is a member of the [docsearch program](https://community.algolia.com/docsearch/#join-docsearch-program),
+   which is the free tier of [Algolia](https://www.algolia.com/).
+1. Algolia hosts a [doscsearch config](https://github.com/algolia/docsearch-configs/blob/master/configs/gitlab.json)
+   for the GitLab docs site, and we've worked together to refine it.
+1. That [config](https://community.algolia.com/docsearch/config-file.html) is
+   parsed by their [crawler](https://community.algolia.com/docsearch/crawler-overview.html)
+   every 24h and [stores](https://community.algolia.com/docsearch/inside-the-engine.html)
+   the [docsearch index](https://community.algolia.com/docsearch/how-do-we-build-an-index.html)
+   on [Algolia's servers](https://community.algolia.com/docsearch/faq.html#where-is-my-data-hosted%3F).
+1. On the docs side, we use a [docsearch layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/docsearch.html) which
+   is present on pretty much every page except <https://docs.gitlab.com/search/>,
+   which uses its [own layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/instantsearch.html). In those layouts,
+   there's a javascript snippet which initiates docsearch by using an API key
+   and an index name (`gitlab`) that are needed for Algolia to show the results.
+
+NOTE: **For GitLab employees:**
+The credentials to access the Algolia dashboard are stored in 1Password. If you
+want to receive weekly reports of the search usage, search the Google doc with
+title "Email, Slack, and GitLab Groups and Aliases", search for `docsearch`,
+and add a comment with your email to be added to the alias that gets the weekly
+reports.
+
+## Monthly release process (versions)
+
+The docs website supports versions and each month we add the latest one to the list.
+For more information, read about the [monthly release process](release_process.md).
+
+## Review Apps for documentation merge requests
+
+If you are contributing to GitLab docs read how to [create a Review App with each
+merge request](../index.md#previewing-the-changes-live).