diff options
Diffstat (limited to 'doc/development/documentation/site_architecture')
4 files changed, 40 insertions, 41 deletions
diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index f101a669968..d92f58e5501 100644 --- a/doc/development/documentation/site_architecture/deployment_process.md +++ b/doc/development/documentation/site_architecture/deployment_process.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Documentation deployment process @@ -36,7 +36,7 @@ and tag all tooling images locally: ``` For each image, there's a manual job under the `images` stage in -[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/.gitlab-ci.yml) which can be invoked at will. +[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/.gitlab-ci.yml) which can be invoked at any time. ## Update an old Docker image with new upstream docs content @@ -46,12 +46,12 @@ for the version in question. ## Porting new website changes to old versions -CAUTION: **Warning:** +WARNING: Porting changes to older branches can have unintended effects as we're constantly changing the backend of the website. Use only when you know what you're doing and make sure to test locally. -The website will keep changing and being improved. In order to consolidate +The website keeps changing and being improved. In order to consolidate those changes to the stable branches, we'd need to pick certain changes from time to time. diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index 21b0c4b6b43..fcf4662502f 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments description: "Learn how GitLab docs' global navigation works and how to add new items." --- @@ -101,11 +101,11 @@ The global nav has 3 components: The available sections are described on the table below: -| Section | Description | -| ------------- | ------------------------------------------ | -| User | Documentation for the GitLab's user UI. | -| Administrator | Documentation for the GitLab's Admin Area. | -| Contributor | Documentation for developing GitLab. | +| Section | Description | +| ------------- | ------------------------------------ | +| User | Documentation for the GitLab UI. | +| Administrator | Documentation for the Admin Area. | +| Contributor | Documentation for developing GitLab. | The majority of the links available on the nav were added according to the UI. The match is not perfect, as for some UI nav items the documentation doesn't @@ -250,7 +250,7 @@ below the doc link: ``` 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. +of its own, it must link to its first sub-item link, mimicking the navigation in GitLab. This must be avoided so that we don't have duplicated links nor two `.active` links at the same time. @@ -292,7 +292,7 @@ and the following syntax rules. an "information" icon on the nav to make the user aware that the feature is EE-only. -CAUTION: **Caution:** +WARNING: All links present on the data file must end in `.html`, not `.md`. Do not start any relative link with a forward slash `/`. diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 3772746e25b..be25a083948 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers -description: "Learn how GitLab's documentation website is architectured." +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Documentation site architecture @@ -14,8 +13,8 @@ static site generator. ## 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 +While the source of the documentation content is stored in the repositories for +each GitLab product, 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 @@ -46,7 +45,7 @@ from where content is sourced, the `gitlab-docs` project, and the published outp H -- symlink --> G ``` -You will not find any GitLab docs content in the `gitlab-docs` repository. +GitLab docs content isn't kept 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: @@ -55,14 +54,14 @@ product, and all together are pulled to generate the docs website: - [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) - [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc) -NOTE: **Note:** +NOTE: In September 2019, we [moved towards a single codebase](https://gitlab.com/gitlab-org/gitlab/-/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. +we can remove this completely. ## Assets @@ -114,7 +113,7 @@ located in the [Dockerfiles directory](https://gitlab.com/gitlab-org/gitlab-docs If you need to rebuild the Docker images immediately (must have maintainer level permissions): -CAUTION: **Caution:** +WARNING: If you change the dockerfile configuration and rebuild the images, you can break the master pipeline in the main `gitlab` repository as well as in `gitlab-docs`. Create an image with a different name first and test it to ensure you do not break the pipelines. @@ -179,7 +178,7 @@ we reference the array with a symbol (`:versions`). Whenever the custom CSS and JavaScript files under `content/assets/` change, make sure to bump their version in the front matter. This method guarantees that -your changes will take effect by clearing the cache of previous files. +your changes 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: @@ -196,7 +195,7 @@ The links pointing to the files should be similar to: <%= @items['/path/to/assets/file.*'].path %> ``` -Nanoc will then build and render those links correctly according with what's +Nanoc then builds and renders those links correctly according with what's defined in [`Rules`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/Rules). ## Linking to source files @@ -236,7 +235,7 @@ If you’re a GitLab team member, find credentials for the Algolia dashboard in the shared [GitLab 1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams). 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. You'll be added to the alias that gets the weekly +and add a comment with your email to be added to the alias that gets the weekly reports. ## Monthly release process (versions) diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md index 547adc89a08..ba5363dbb71 100644 --- a/doc/development/documentation/site_architecture/release_process.md +++ b/doc/development/documentation/site_architecture/release_process.md @@ -1,7 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Docs monthly release process @@ -26,7 +26,7 @@ To add a new charts version: version mapping. Note that only the `major.minor` version is needed. 1. Create a new merge request and merge it. -TIP: **Tip:** +NOTE: It can be handy to create the future mappings since they are pretty much known. In that case, when a new GitLab version is released, you don't have to repeat this first step. @@ -44,14 +44,14 @@ this needs to happen when the stable branches for all products have been created ``` A new `Dockerfile.12.0` should have been created and `.gitlab-ci.yml` should - have the branches variables updated into a new branch. They will be automatically + have the branches variables updated into a new branch. They are automatically committed. 1. Push the newly created branch, but **don't create a merge request**. - Once you push, the `image:docker-singe` job will create a new Docker image + After you push, the `image:docs-single` job creates a new Docker image tagged with the branch name you created in the first step. In the end, the - image will be uploaded in the [Container Registry](https://gitlab.com/gitlab-org/gitlab-docs/container_registry) - and it will be listed under the `registry` environment folder at + image is uploaded in the [Container Registry](https://gitlab.com/gitlab-org/gitlab-docs/container_registry) + and it is listed under the `registry` environment folder at `https://gitlab.com/gitlab-org/gitlab-docs/-/environments/folders/registry` (must have developer access). @@ -66,7 +66,7 @@ Visit `http://localhost:4000/12.0/` to see if everything works correctly. ## 3. Create the release merge request -NOTE: **Note:** +NOTE: To be [automated](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/750). Now it's time to create the monthly release merge request that adds the new @@ -114,20 +114,20 @@ version and rotates the old one: The versions dropdown is in a way "hardcoded". When the site is built, it looks at the contents of `content/_data/versions.yaml` and based on that, the dropdown -is populated. So, older branches will have different content, which means the -dropdown will list one or more releases behind. Remember that the new changes of +is populated. Older branches have different content, which means the +dropdown list is one or more releases behind. Remember that the new changes of the dropdown are included in the unmerged `release-X-Y` branch. The content of `content/_data/versions.yaml` needs to change for all online versions (stable branches `X.Y` of the `gitlab-docs` project): -1. Run the Rake task that will create all the respective merge requests needed to - update the dropdowns and will be set to automatically be merged when their +1. Run the Rake task that creates all the respective merge requests needed to + update the dropdowns. Set these to automatically be merged when their pipelines succeed: - NOTE: **Note:** + NOTE: The `release-X-Y` branch needs to be present locally, - and you need to have switched to it, otherwise the Rake task will fail. + and you need to have switched to it, otherwise the Rake task fails. ```shell git checkout release-X-Y @@ -138,13 +138,13 @@ versions (stable branches `X.Y` of the `gitlab-docs` project): to check that their pipelines pass, and once all are merged, proceed to the following and final step. -TIP: **Tip:** +NOTE: In case a pipeline fails, see [troubleshooting](#troubleshooting). ## 5. Merge the release merge request The dropdown merge requests should have now been merged into their respective -version (stable `X.Y` branch), which will trigger another pipeline. At this point, +version (stable `X.Y` branch), which triggers another pipeline. At this point, you need to only babysit the pipelines and make sure they don't fail: 1. Check the [pipelines page](https://gitlab.com/gitlab-org/gitlab-docs/pipelines) @@ -152,9 +152,9 @@ you need to only babysit the pipelines and make sure they don't fail: 1. After all the pipelines of the online versions succeed, merge the release merge request. 1. Finally, run the [`Build docker images weekly` pipeline](https://gitlab.com/gitlab-org/gitlab-docs/pipeline_schedules) - that will build the `:latest` and `:archives` Docker images. + that builds the `:latest` and `:archives` Docker images. -Once the scheduled pipeline succeeds, the docs site will be deployed with all +Once the scheduled pipeline succeeds, the docs site is deployed with all new versions online. ## Troubleshooting @@ -163,7 +163,7 @@ Releasing a new version is a long process that involves many moving parts. ### `test_internal_links_and_anchors` failing on dropdown merge requests -DANGER: **Deprecated:** +WARNING: We now pin versions in the `.gitlab-ci.yml` of the respective branch, so the steps below are deprecated. |