diff options
| -rw-r--r-- | doc/development/documentation/architecture/global_nav.md | 255 | ||||
| -rw-r--r-- | doc/development/documentation/architecture/index.md | 55 | ||||
| -rw-r--r-- | doc/development/documentation/index.md | 13 |
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 |