Simplify README

[ci skip]

1 files changed, 173 insertions, 172 deletions

diff --git a/README.md b/README.md
index 5b2ab084..800224ca 100644
--- a/README.md
+++ b/README.md
@@ -2,258 +2,259 @@
 
 # GitLab Documentation
 
-- The [GitLab Documentation](https://docs.gitlab.com) website is generated using [Nanoc](http://nanoc.ws).
-- [Writing Documentation](https://docs.gitlab.com/ce/development/writing_documentation.html)
-- [Style Guide](https://docs.gitlab.com/ce/development/doc_styleguide.html)
-- [Community Writers](https://about.gitlab.com/handbook/product/technical-writing/community-writers/)
+This 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.
 
-## Contributing
-
-Read more in [CONTRIBUTING.md](CONTRIBUTING.md).
-
-## License
+You will not find any GitLab docs content here. All documentation files are
+hosted in the respective repository of each product (see the following section).
 
-See [LICENSE](LICENSE).
-
-## Development
-
-### Requirements
+## Projects we pull from
 
-To preview `docs.gitlab.com` locally, you'll need:
+There are currently 4 products that are pulled and generate the docs website:
 
-- Unix
-- Ruby 2.4.0
-- Bundler
-- Repositories
-  - GitLab CE
-  - GitLab EE
-  - GitLab Multi Runner
-  - GitLab Omnibus
-  - GitLab Docs
+- [GitLab Enterprise Edition](https://gitlab.com/gitlab-org/gitlab-ee)
+- [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-ce)
+- [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab)
+- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner)
 
-> Note: On Windows, the process described here would be different, but as most of contributors use Unix, we'll go over this process for MacOs and Linux users only.
+**NOTE:**
+Although GitLab Community Edition is generated, it is hidden from the website
+as it's a subset of the Enterprise Edition. We generate it for consistency,
+until the [GitLab codebase is unified](https://gitlab.com/gitlab-org/gitlab-ee/issues/2952).
 
-### Installing dependencies
+## Contributing
 
-#### Ruby 2.4.0
+Read [CONTRIBUTING.md](CONTRIBUTING.md) for an overview of the Developer
+Certificate of Origin + License.
 
-If you don't have Ruby installed in your computer, [install Ruby 2.4.0](https://www.ruby-lang.org/en/documentation/installation/) directly.
+To contribute to the content of GitLab docs, see:
 
-If you already have other Ruby versions installed, you can use a Ruby version manager to install Ruby 2.4.0 in your system.
+- [Writing documentation](https://docs.gitlab.com/ce/development/writing_documentation.html)
+- [Style guide](https://docs.gitlab.com/ce/development/doc_styleguide.html)
+- [Community writers](https://about.gitlab.com/community-writers/)
 
-Check your Ruby version with `ruby --version`.
+## License
 
-To install multiple Ruby versions on MacOS or Linux, we recommend you use RMV:
+See [LICENSE](LICENSE).
 
-- Install [RVM](https://rvm.io/rvm/install)
-- Install Ruby 2.4.0 with `rvm install 2.4.0`
+## Development under GDK
 
-#### Bundler
+See [how to preview the docs changes locally using GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md).
 
-[Bundler](https://bundler.io/) is an incredible dependency manager. Install it by running `gem install bundler`.
+## Development using this repo
 
-#### Repositories
+You can clone and use this repo to preview the website as seen on
+https://docs.gitlab.com.
 
-**GitLab Team members:** clone the required repos to your machine. Navigate to the directory you'd like to have them, then clone with SSH:
+### Requirements
 
-- GitLab CE: `git clone git@gitlab.com:gitlab-org/gitlab-ce.git`
-- GitLab EE: `git clone git@gitlab.com:gitlab-org/gitlab-ee.git`
-- GitLab Runner: `git clone git@gitlab.com:gitlab-org/gitlab-runner.git`
-- GitLab Omnibus: `git clone git@gitlab.com:gitlab-org/omnibus-gitlab.git`
-- GitLab Docs: `git clone git@gitlab.com:gitlab-com/gitlab-docs.git`
+Here's what you will need to have:
 
-**GitLab Contributors:** fork each of these projects and clone them to your local computer:
+- A Unix/Linux environment
+- Ruby 2.4+
+- Bundler
 
-- GitLab CE: https://gitlab.com/gitlab-org/gitlab-ce/
-- GitLab EE: https://gitlab.com/gitlab-org/gitlab-ee/
-- GitLab Runner: https://gitlab.com/gitlab-org/gitlab-runner
-- GitLab Omnibus: https://gitlab.com/gitlab-org/omnibus-gitlab
-- GitLab Docs: https://gitlab.com/gitlab-com/gitlab-docs
+**Note:**
+On Windows, the process described here would be different, but as most of
+contributors use Unix, we'll go over this process for macOS and Linux users.
 
-### Bring Everything Together
+#### Ruby
 
-Now that we have everything required, we need to add symlinks, so GitLab Docs can talk to the remaining repos.
+The recommended way is to use a Ruby version manager to install Ruby in your
+system.
 
-#### Symlinks
+One way is to use RMV:
 
-- In a terminal window, navigate to your local path to where you just cloned GitLab Docs
-- Output the path by running `pwd`:
+1. Install [RVM](https://rvm.io/rvm/install)
+1. Install the latest Ruby:
 
-    ```
-    $ pwd
-    /Users/username/dir/gitlab-docs
+    ```sh
+    rvm install 2.5.0
     ```
 
-- In a terminal window, navigate to your local path to where you just cloned GitLab CE
-- Output the path by running `pwd`:
+1. Use the newly installed Ruby:
 
+    ```sh
+    rvm use 2.5.0
     ```
-    $ pwd
-    /Users/username/dir/gitlab-ce
-    ```
-
-- Copy the output and create a symlink between GitLab Docs (`content/`) and GitLab CE (`/doc/`), by running `ln -s /Users/username/dir/gitlab-ce/doc /Users/username/dir/gitlab-docs/content/ce`. Of course, adjust the paths according to the output of `pwd`.
 
-- Repeat the process to the other three repos:
-  - GitLab EE: `ln -s /Users/username/dir/gitlab-ee/doc /Users/username/dir/gitlab-docs/content/ee`
-  - Runner: `ln -s /Users/username/dir/gitlab-runner/docs /Users/username/dir/gitlab-docs/content/runner`
-  - Omnibus: `ln -s /Users/username/dir/omnibus-gitlab/doc /Users/username/dir/gitlab-docs/content/omnibus`
-- Open GitLab Docs in a terminal window and check if you have all the foour there (`ee`, `ce`, `runner`, `omnibus`): `ls content`
-
-If they're there, we're good to go!
-
-### Install Docs dependencies
+Check your Ruby version with `ruby --version`.
 
-Now let's make Bundler deal with the dependencies defined in the `Gemfile`:
+#### Bundler
 
-- Open GitLab Docs in a terminal window
-- Switch to Ruby 2.4.0: `rvm 2.4.0`
-- Run `bundle install`
+[Bundler](https://bundler.io/) is a Ruby dependency manager. Install it with:
 
-### Preview the Docs website
+```
+gem install bundler
+```
 
-- `bundle exec nanoc live`
+#### Clone the repositories
 
-This will host the site at `localhost:3000`. Changes will be reloaded automatically using [Guard Nanoc](https://github.com/guard/guard-nanoc).
+Since this process will clone a few repositories, it might be a good idea to
+create a separate directory to have them all together. For example, let's say
+the directory will be under your user's home directory. Open a terminal and
+execute:
 
-#### Preview on mobile
+```sh
+mkdir ~/dev/gitlab
+```
 
-If you want to check how your changes look on mobile devices, you can preview the Docs site with
-your own devices, as long as they are connected to the same network as your computer.
+Once you do that, navigate to the directory you'd like the repos to be cloned:
 
-To do that, we need to change the IP address Nanoc is serving on from the default `http://127.0.0.1` to your computer's [private IPv4 address](https://www.howtogeek.com/236838/how-to-find-any-devices-ip-address-mac-address-and-other-network-connection-details/).
+```sh
+cd ~/dev/gitlab/
+```
 
-Once you know what's your computer's private IPv4, use the flag `-o` with the command
-`nanoc live`. For example, let's say your current IPv4 address is `192.168.0.105`:
+Then, it's time to clone the needed repositories.
 
-```shell
-bundle exec nanoc live -o 192.168.0.105
-```
+1. First of all, clone the docs website repository:
 
-Now, open your mobile's browser and type `http://192.168.0.105:3000`, and you should
-be able to navigate through the docs site. This process applies to preview the docs site
-on every device connected to your network.
+    ```sh
+    ## Using SSH (for members that have Developer access)
+    git clone git@gitlab.com:gitlab-com/gitlab-docs.git
 
-### Extra Step
+    ## Using HTTPS (for external contributors)
+    git clone https://gitlab.com/gitlab-com/gitlab-docs.git
+    ```
 
-To pull down the documentation content, run `rake pull_repos`. If you want to force-delete the `tmp/` and `content/` folders so the task will run without manual intervention, run `RAKE_FORCE_DELETE=true rake pull_repos`.
+1. Then, clone the repositories you wish to contribute changes to the documentation.
+   For **GitLab contributors**, that do not have Developer access to the projects,
+   fork the ones you want (see [projects we pull from](#projects-we-pull-from))
+   and then clone them by using your forked version (replace `<username>` with
+   your own username):
 
-## Projects we pull from
+     ```sh
+     ## Using HTTPS (for members that do not have Developer access)
 
-We pull from the following projects:
+     git clone https://gitlab.com/<username>/gitlab-ce.git
+     git clone https://gitlab.com/<username>/gitlab-ee.git
+     git clone https://gitlab.com/<username>/gitlab-runner.git
+     git clone https://gitlab.com/<username>/omnibus-gitlab.git
+     ```
 
-- [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-ce)
-- [GitLab Enterprise Edition](https://gitlab.com/gitlab-org/gitlab-ee)
-- [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab)
-- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner)
+     For members that have Developer access (usually the **GitLab Team members**),
+     clone the required repos using SSH:
 
-## Examples and Resources
+     ```sh
+     ## Using SSH (for members that have Developer access)
 
-### Open Source Nanoc Sites
+     git clone git@gitlab.com:gitlab-org/gitlab-ce.git
+     git clone git@gitlab.com:gitlab-org/gitlab-ee.git
+     git clone git@gitlab.com:gitlab-org/gitlab-runner.git
+     git clone git@gitlab.com:gitlab-org/omnibus-gitlab.git
+     ```
 
-**NOTE**: We use Nanoc 4.0 which has some significant differences from 3.0, be aware that not all example sites use 4.0.
+### Create the content symlinks
 
-- [Nanoc's Website](https://github.com/nanoc/nanoc.ws)
-- [GitHub Developer Site](https://github.com/github-archive/developer.github.com)
-- [Spree Guides](https://github.com/spree/spree/tree/master/guides)
-- [Atom Flight Manual](https://github.com/atom/flight-manual.atom.io)
-- [Prometheus Docs](https://github.com/prometheus/docs)
+Nanoc expects the Markdown files to be under `content/<slug>`, where `<slug>`
+is the slug of each product as defined in [`.nanoc.yaml`](/nanoc.yaml).
 
-### Good Documentation
+If you have already cloned the repository (or repositories) you want to
+contribute to, you can easily satisfy Nanoc's requirement by symlinking only
+the directory that holds the documentation content.
 
-- [SendGrid](https://sendgrid.com/docs)
-- [Stripe](https://stripe.com/docs)
-- [Stripe API](https://stripe.com/docs/api)
-- [CircleCI](https://circleci.com/docs)
-- [Heroku](https://devcenter.heroku.com/)
-- [Slack](https://get.slack.help/hc/en-us)
-- [Slack API](https://api.slack.com/)
-- [Kong](https://getkong.org/docs/)
+1. Open a terminal and navigate to the directory where gitlab-docs was cloned.
+1. For each one of the products, create the symlink:
 
-## Requirements/Goals
+    ```sh
+    ln -s ~/dev/gitlab/gitlab-ce/doc ~/dev/gitlab/gitlab-docs/content/ce
+    ln -s ~/dev/gitlab/gitlab-ee/doc ~/dev/gitlab/gitlab-docs/content/ee
+    ln -s ~/dev/gitlab/omnibus-gitlab/doc ~/dev/gitlab/gitlab-docs/content/omnibus
+    ln -s ~/dev/gitlab/gitlab-runner/docs ~/dev/gitlab/gitlab-docs/content/runner
+    ```
 
-- [x] Feature parity with the existing [docs.gitlab.com](https://docs.gitlab.com/)
-- [x] Use GitLab CI / GitLab Pages for compilation, deployment, and hosting of the Documentation site.
-- [x] Sections for Community Edition, Enterprise Edition, GitLab CI, and Omnibus.
-- [x] Pull documentation from the repositories mentioned above.
-- [ ] Versioned documentation (e.g. switch between documentation for 9.0, 9.1, 9.2, 9.3, "latest", etc.)
-- [x] Search the documentation (Can either re-use existing Documentation search functionality or implement search using Algolia or something else? Ideally simple and open source, but it doesn't really matter too much.)
-- [x] Link to "Edit on GitLab.com" for every page to encourage contribution.
-- [x] Responsive design.
+1. Check if the symlinks where successfully created:
 
-### Nice-to-haves
+    ```sh
+    ls -la content/
+    ```
 
-- [ ] Some way to embed/package the site inside the Rails app so the documentation can be included with the application itself. This would be nice for users behind firewalls, etc. This _should not_ be handled by Rails itself, as that causes all kinds of problems. It should just be a set of static pages.
-- [ ] Some way to export the documentation as PDF/ePub for use offline.
-- [ ] Future-proofing for internationalization.
-- [x] Tests for working internal links and such. (Nanoc includes this by default!)
-- [x] A blog post explaining how we do all this using GitLab, GitLab CI, and GitLab Pages, as well as (almost all?) open source tools.
-- [x] Breadcrumbs for navigating between pages.
-- [x] Auto-generated Table of Contents for every page.
-- [x] Anchor links for every page section.
-- [x] Syntax highlighting with Rouge.
-- [ ] Auto-generated documentation structure based on YML frontmatter.
-- [ ] Version dropdown that links to the current page for that version (if it exists).
-- [ ] Automatically generated API documentation.
+If they're there, we're good to go!
 
-## Implementation details
+**Note:** You can use the `pwd` command when in the terminal to check the
+directory path you are currently in and use that output to use with the symlinks
+commands above.
 
-### URLs
+### Install Nanoc's dependencies
 
-URLs should be in the form of `https://docs.gitlab.com/PRODUCT/LANGUAGE/VERSION/documentation-file-name.html`.
+Now let's make Bundler deal with the dependencies defined in the
+[`Gemfile`](/Gemfile):
 
-Examples:
+1. Open a terminal and navigate to the GitLab Docs repo
+1. Switch to Ruby using RVM:
 
-- `https://docs.gitlab.com/ce/en/9-0/documentation-file-name.html`
-- `https://docs.gitlab.com/ee/en/9-1/documentation-file-name.html`
-- `https://docs.gitlab.com/omnibus/en/9-5/documentation-file-name.html`
+    ```sh
+    rvm use 2.5.0
+    ```
 
-Relative paths between documentation pages would need to automatically correct to the right product, language, and version.
+1. Run:
 
-### Pulling `docs` directories from the CE, EE, and Omnibus repositories
+    ```sh
+    bundle install
+    ```
 
-#### Requirements
+### Preview the Docs website
 
-- Needs to be able to use Git tags to pull in versions.
-- Needs to be performant, can't take a huge amount of time to generate the documentation site. Goal is 15 minutes maximum.
-- Fully runnable locally so we can easily test changes locally.
+Run the following command to bring the embedded web server up:
 
-#### Possible options
+```sh
+bundle exec nanoc live
+```
 
-**Submodules**:
+This will generate and the site and you will be able to view it in your browser
+at <http://localhost:3000>. Any changes you make to either the website or the
+content of the docs, will be reloaded automatically.
 
-Include the `docs` directories for each repo in the gitlab-docs repo using submodules.
+To preview the site on another port, use:
 
-- Not well-supported by GitLab
-- Not sure if submodules can be used to pull down just a directory?
+```sh
+bundle exec nanoc live -p 3004
+```
 
-**Artifacts**:
+This will generate and the site and you will be able to view it in your browser
+at <http://localhost:3004>.
 
-Have the build process for the Docs site pull artifacts down from each repository.
+#### Preview on mobile
 
-- Artifacts would need to be hosted long-term by CI.
-- Can't generate artifacts exclusively for tags, would be generated for every commit.
+If you want to check how your changes look on mobile devices, you can preview
+the Docs site with your own devices, as long as they are connected to the same
+network as your computer.
 
-**Pull in repositories dynamically** (this is what we went with):
+To do that, we need to change the IP address Nanoc is serving on from the
+default `http://127.0.0.1` to your computer's
+[private IPv4 address](https://www.howtogeek.com/236838/how-to-find-any-devices-ip-address-mac-address-and-other-network-connection-details/).
 
-Pull down the repositories during the build process and splice the docs directories together in the right places for use with the nanoc site.
+Once you know what's your computer's private IPv4, use the flag `-o`. For
+example, let's say your current IPv4 address is `192.168.0.105`:
 
-**Include the built site in the repository itself**:
+```sh
+bundle exec nanoc live -o 192.168.0.105
+```
 
-This is almost definitely out of the question due to how bloated the repository would become and how much of a pain it'd be to maintain this, but it is an option and would make the build process quite a bit faster.
+Now, open your mobile's browser and type `http://192.168.0.105:3000`, and you should
+be able to navigate through the docs site. This process applies to previewing the
+docs site on every device connected to your network.
 
-### Performance
+## Contributing to the docs website itself
 
-- Use artifacts to store previous versions of the site so they don't have to be regenerated constantly.
-- Nanoc is supposedly quite fast.
+If you want to just contribute to the docs website, and not the content, you
+can use the following command to automatically pull the docs content in order
+to have something to preview:
 
-### Differentiating between CE and EE features
+```sh
+bundle exec rake pull_repos
+```
 
-One potential problem with having separate docs for CE vs. EE is the inability to easily track differences between the two. Their documentation won't necessarily be kept in-sync and pages that differ between CE and EE may cause conflicts when merging the CE repository into EE.
+This will pull all the docs content under the `tmp/` directory and copy it in
+`content/`. You can then [preview the website](preview-the-docs-website).
 
-One potential solution to this problem is to include the EE docs inside the CE repository and then label pages as either Universal or EE-only (using frontmatter). The same could be done for specific sections on the page. This has the potential downside of complicating the documentation-writing process for contributors, but arguably the complexity of the CE/EE repositories already exists, so we're not really adding complexity so much as switching its form.
+If you want to force-delete the `tmp/` and `content/` folders so the task will
+run without manual intervention, run:
 
-The Atom Flight Manual has [the ability to switch between platforms for given pages](http://flight-manual.atom.io/using-atom/sections/atom-selections/), this code could be repurposed for including/excluding features based on whether the documentation is CE or EE ([Source](https://raw.githubusercontent.com/atom/flight-manual.atom.io/4c8f8d14e13b84584fe206e914ea06c6dc2b7a96/content/using-atom/sections/atom-selections.md)).
+```sh
+RAKE_FORCE_DELETE=true rake pull_repos
+```
 
 ## Review Apps for documentation merge requests
 
@@ -263,7 +264,7 @@ merge request: https://docs.gitlab.com/ee/development/writing_documentation.html
 ## Deployment process
 
 We use [GitLab Pages][pages] to build and host this website. You can see
-`.gitlab-ci.yml` for more information.
+[`.gitlab-ci.yml`](/.gitlab-ci.yml) for more information.
 
 We also use [scheduled pipelines](https://docs.gitlab.com/ee/user/project/pipelines/schedules.html)
 to build the site once an hour.