Resets branch against master, add back docs architecture guidelinesdocs-add-global-nav

3 files changed, 320 insertions, 3 deletions

diff --git a/doc/development/documentation/architecture/global_nav.md b/doc/development/documentation/architecture/global_nav.md
new file mode 100644
index 00000000000..6c37035c8c3
--- /dev/null
+++ b/doc/development/documentation/architecture/global_nav.md
@@ -0,0 +1,255 @@
+# Global navigation
+
+[Introduced](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/362)
+in November 2018, the global nav adds to the left sidebar the ability to
+navigate and explore the contents of GitLab's documentation.
+
+## How it works
+
+The global nav has 3 components:
+
+- **Section**
+  - Category
+    - Doc
+
+The available sections are:
+
+- User
+- Administrator
+- Contributor
+
+The links available on the nav were added according to the UI. **User** docs
+follow the user UI as well as **Administrator** docs follow GitLab's admin area.
+
+The match is not perfect, as for some UI nav items the documentation doesn't
+apply. There are also other links to help the new users to discover the documentation.
+
+The last section, **Contributor** docs, are not part of the UI, but were added
+for improved navigation and discoverability.
+
+To check the improvements planned, read though the
+[global nav epic](https://gitlab.com/groups/gitlab-com/-/epics/21).
+
+CAUTION: **Attention!**
+**Do not** [add items](#adding-new-items-to-the-global-nav) to the global nav without
+the consent of one of the technical writers.
+
+## Composition
+
+The global nav is built from two files:
+
+- [Data](#data-file)
+- [Layout](#layout-file)
+
+The data file feeds the layout with the links to the docs. The layout organizes
+the data among the nav in containers properly styled.
+
+### Data file
+
+The [data file](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/content/_data/global-nav.yaml)
+is structured in three components: sections, categories, and docs.
+
+DANGER: **Important!**
+All links present on the data file must end in `.html`, not `.md`. Do not
+start any relative link with a slash `/`.
+
+#### Sections
+
+Each section represents the higher-level nav item. It's composed by
+title and URL:
+
+```yaml
+sections:
+  - section_title: Text
+    section_url: 'link'
+```
+
+The section can stand alone or contain categories within.
+
+#### Categories
+
+Each category within a section composes the second level of the nav.
+It includes the category title and link. It can stand alone in the nav or contain
+a third level of sub-items.
+
+Example of section and standing alone category:
+
+```yaml
+- section_title: Section title
+  section_url: 'section-link'
+  section_categories:
+    - category_title: Category title
+      category_url: 'category-link'
+```
+
+Example of section with two stand-alone categories:
+
+```yaml
+- section_title: Section title
+  section_url: 'section-link'
+  section_categories:
+    - category_title: Category 1 title
+      category_url: 'category-1-link'
+
+    - category_title: Category 2 title
+      category_url: 'category-2-link'
+```
+
+For clarity, **always** add a blank line between categories.
+
+If a category URL is not present in CE (it's an EE-only document), add the
+attribute `ee_only: true` below the category link. Example:
+
+```yaml
+- category_title: Category title
+  category_url: 'category-link'
+  ee_only: true
+```
+
+If the category links to an external URL, e.g., [GitLab Design System](https://design.gitlab.com),
+add the attribute `external_url: true` below the category title. Example:
+
+```yaml
+- category_title: GitLab Design System
+  category_url: 'https://design.gitlab.com'
+  external_url: true
+```
+
+#### Docs
+
+Each doc represents the third level of nav links. They must be always
+added within a category.
+
+Example with one doc link:
+
+```yaml
+- category_title: Category title
+  category_url: 'category-link'
+  docs:
+    - doc_title: Document title
+      doc_url: 'doc-link'
+```
+
+A category supports as many docs as necessary, but, for clarity, try to not
+overpopulate a category.
+
+Example with multiple docs:
+
+
+```yaml
+- category_title: Category title
+  category_url: 'category-link'
+  docs:
+    - doc_title: Document 1 title
+      doc_url: 'doc-1-link'
+    - doc_title: Document 2 title
+      doc_url: 'doc-2-link'
+```
+
+Whenever a document is only present in EE, add the attribute `ee-only: true`
+below the doc link. Example:
+
+```yaml
+- doc_title: Document 2 title
+  doc_url: 'doc-2-link'
+  ee_only: true
+```
+
+If you need to add a document in an external URL, add the attribute `external_url`
+below the doc link:
+
+```yaml
+- doc_title: Document 2 title
+  doc_url: 'doc-2-link'
+  external_ur: true
+```
+
+All nav links are clickable. If the higher-level link does not have a link
+of its own, it must link to its first sub-item link, mimicking GitLab's navigation.
+This must be avoided so that we don't have duplicated links nor two `.active` links
+at the same time.
+
+Example:
+
+```yaml
+- category_title: Operations
+  category_url: 'user/project/integrations/prometheus_library/'
+  # until we have a link to operations, the first doc link is
+  # repeated in the category link
+  docs:
+    - doc_title: Metrics
+      doc_url: 'user/project/integrations/prometheus_library/'
+```
+
+#### Syntax
+
+For all components (sections, categories, and docs), respect the indentation
+and the following syntax rules.
+
+##### Titles
+
+- Use sentence case, capitalizing feature names.
+- There's no need to wrap the titles, unless there's a special char in it. E.g.,
+  in `GitLab CI/CD`, there's a `/` present, therefore, it must be wrapped in quotes.
+  As convention, wrap the titles in double quotes: `category_title: "GitLab CI/CD"`.
+
+##### URLs
+
+- As convention, always wrap URLs in single quotes `'url'`.
+- Always use relative paths against the home of CE and EE. Examples:
+  - For `https://docs.gitlab.com/ee/README.html`, the relative URL is `README.html`.
+  - For `https://docs.gitlab.com/ee/user/project/cycle_analytics.html`, the relative
+    URL is `user/project/cycle_analytics.html`
+- For `README.html` files, add the complete path `path/to/README.html`.
+- For `index.html` files, use the canonical URL: `path/to/`.
+- For EE-only docs, use the same relative path, but add the attribute `ee_only: true` below
+  the `doc_url` or `category_url`, as explained above. This will guarantee that when
+  the user is looking at the CE docs, it will link to the EE docs. It also displays
+  an "info" icon on the CE nav to make the user aware that it's a different link.
+
+Examples:
+
+```yaml
+    - category_title: Issues
+      category_url: 'user/project/issues/'
+      # note that the above URL does not start with a slash and 
+      # does not include index.html at the end
+
+      docs:
+        - doc_title: Service Desk
+          doc_url: 'user/project/service_desk.html'
+          ee_only: true
+          # note that the URL above ends in html and, as the
+          # document is EE-only, the attribute ee_only is set to true.
+```
+
+### Layout file
+
+The [layout](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/layouts/global_nav.html)
+is fed by the [data file](#data-file), builds the global nav, and is rendered by the
+[default](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/layouts/default.html) layout.
+
+Important information:
+
+- For having the relative paths working in CE, EE, Omnibus, Runner, and whichever
+  direct subdir of docs.gitlab.com, all links point to `ee/`, except the links from
+  the CE nav. This rules is defined by `<% if dir != 'ce' %>`.
+- The nav is styled in the general `stylesheet.scss`. To change its styles, keep them
+  grouped for better development among the team.
+- The URL components have their unique styles set by the CSS classes `.level-0`,
+  `.level-1`, and `.level-2`. To adjust the link's font size, padding, color, etc,
+  use these classes. This way we guarantee that the rules for each link do not conflict
+  with other rules in the stylesheets.
+
+## Adding new items to the global nav
+
+To add a new doc to the nav, first and foremost, check with the technical writing team:
+
+- If it's applicable
+- What's the exact position the doc will be added to the nav
+
+Once you get their approval and their guidance in regards to the position on the nav,
+add submit a merge request to the docs site, adding your document to the
+[global nav data file](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/content/_data/global-nav.yaml).
+
+Don't forget to ask them to review your changes before merging.
diff --git a/doc/development/documentation/architecture/index.md b/doc/development/documentation/architecture/index.md
new file mode 100644
index 00000000000..03d8ee0cf0f
--- /dev/null
+++ b/doc/development/documentation/architecture/index.md
@@ -0,0 +1,55 @@
+# Documentation architecture
+
+Learn how we build and architecture [`gitlab-docs`](https://gitlab.com/gitlab-com/gitlab-docs)
+and deploy it to <https://docs.gitlab.com>.
+
+## Assets
+
+To provide an optimized site structure, design, and a search-engine friendly
+website, along with a discoverable documentation, we use a few assets for
+the GitLab Documentation website.
+
+### Libraries
+
+- [Bootstrap 3.3 components](https://getbootstrap.com/docs/3.3/components/)
+- [Bootstrap 3.3 JS](https://getbootstrap.com/docs/3.3/javascript/)
+- [jQuery](https://jquery.com/) 3.2.1
+- [Clipboard JS](https://clipboardjs.com/)
+- [Font Awesome 4.7.0](https://fontawesome.com/v4.7.0/icons/)
+
+### SEO
+
+- [Schema.org](https://schema.org/)
+- [Google Analytics](https://marketingplatform.google.com/about/analytics/)
+- [Google Tag Manager](https://developers.google.com/tag-manager/)
+
+## Global nav
+
+To understand how the global nav (left sidebar) is built, please
+read through the [global navigation](global_nav.md) doc.
+
+## Deployment
+
+The docs site is deployed to production with GitLab Pages, and previewed in
+merge requests with Review Apps.
+
+The deployment aspects will be soon transfered from the [original document](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md)
+to this page.
+
+<!--
+## Repositories
+
+TBA
+
+## Search engine
+
+TBA
+
+## Versions
+
+TBA
+
+## Helpers
+
+TBA
+-->
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index b7990e1b558..32252436065 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -368,6 +368,16 @@ You can combine one or more of the following:
       = link_to 'Help page', help_page_path('user/permissions')
     ```
 
+## Docs site architecture
+
+Read through [docs architecture](architecture/index.md) to learn
+how we architecture, build, and deploy the docs site, <https://docs.gitlab.com>, and
+to check all the assets and libraries available.
+
+### Global navigation
+
+Read through the [global navigation](architecture/global_nav.md) doc.
+
 ## General Documentation vs Technical Articles
 
 ### General documentation
@@ -679,6 +689,3 @@ GitLab uses [danger bot](https://github.com/danger/danger) for some elements in
 code review. For docs changes in merge requests, whenever a change under `/doc`
 is made, the bot leaves a comment for the author to mention `@gl-docsteam`, so
 that the docs can be properly reviewed.
-
-[gitlab-map]: https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.png
-[graffle]: https://gitlab.com/gitlab-org/gitlab-design/blob/d8d39f4a87b90fb9ae89ca12dc565347b4900d5e/production/resources/gitlab-map.graffle