diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/improvement-workflow.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/index.md | 28 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide.md | 22 |
3 files changed, 28 insertions, 24 deletions
diff --git a/doc/development/documentation/improvement-workflow.md b/doc/development/documentation/improvement-workflow.md index c8e9368fb74..3bbb45debfb 100644 --- a/doc/development/documentation/improvement-workflow.md +++ b/doc/development/documentation/improvement-workflow.md @@ -20,7 +20,7 @@ to accomplish their work with GitLab. ## How to update the docs -1. Click "Edit this Page" at the bottom of any page on docs.gitlab.com, or navigate to +1. Click "Edit this Page" at the bottom of any page on <https://docs.gitlab.com>, or navigate to one of the repositories and doc paths listed on the [GitLab Documentation guidelines](index.md) page. Work in a fork if you do not have developer access to the GitLab project. 1. Follow the described standards and processes listed on that Guidelines page, diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 4ad24d08d17..a5b47b3a5c0 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -8,19 +8,18 @@ GitLab's documentation is [intended as the single source of truth (SSOT)](https: In addition to this page, the following resources can help you craft and contribute documentation: -- [Style Guide](styleguide.md) - What belongs in the docs, language guidelines, and more. +- [Style Guide](styleguide.md) - What belongs in the docs, language guidelines, Markdown standards to follow, and more. - [Structure and template](structure.md) - Learn the typical parts of a doc page and how to write each one. - [Workflows](workflow.md) - A landing page for our key workflows: - [Documentation process for feature changes](feature-change-workflow.md) - Adding required documentation when developing a GitLab feature. - [Documentation improvement workflow](improvement-workflow.md) - New content not associated with a new feature. -- [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) - A reference for the markdown implementation used by GitLab's documentation site and about.gitlab.com. -- [Site architecture](site_architecture/index.md) - How docs.gitlab.com is built. +- [Markdown Guide](../../user/markdown.md) - A reference for all markdown syntax supported by GitLab. +- [Site architecture](site_architecture/index.md) - How <http://docs.gitlab.com> is built. ## Source files and rendered web locations -Documentation for GitLab, GitLab Runner, and Omnibus is published to [docs.gitlab.com](https://docs.gitlab.com). Documentation for GitLab is also published within the application at `/help` on the domain of the GitLab instance. - -At `/help`, only help for your current edition and version is included. Help for other versions is available at docs.gitlab.com. +Documentation for GitLab, GitLab Runner, Omnibus GitLab and Charts are published to <https://docs.gitlab.com>. Documentation for GitLab is also published within the application at `/help` on the domain of the GitLab instance. +At `/help`, only help for your current edition and version is included. Help for other versions is available at <https://docs.gitlab.com/archives/>. The source of the documentation exists within the codebase of each GitLab application in the following repository locations: @@ -29,6 +28,7 @@ The source of the documentation exists within the codebase of each GitLab applic | [GitLab](https://gitlab.com/gitlab-org/gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab/tree/master/doc) | | [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) | | [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab/tree/master/doc) | +| [Charts](https://gitlab.com/gitlab-org/charts/gitlab) | [`/doc`](https://gitlab.com/gitlab-org/charts/gitlab/tree/master/doc) | Documentation issues and merge requests are part of their respective repositories and all have the label `Documentation`. @@ -55,8 +55,8 @@ See the [Structure](styleguide.md#structure) section of the [Documentation Style Changing a document's location requires specific steps to ensure that users can seamlessly access the new doc page, whether they are accessing content -on a GitLab instance domain at `/help` or at docs.gitlab.com. Be sure to ping a -GitLab technical writer if you have any questions during the process (such as +on a GitLab instance domain at `/help` or at <https://docs.gitlab.com>. Be sure to assign a +technical writer if you have any questions during the process (such as whether the move is necessary), and ensure that a technical writer reviews this change prior to merging. @@ -132,7 +132,7 @@ land on the doc via `/help`. If the documentation page being relocated already has Disqus comments, we need to preserve the Disqus thread. -Disqus uses an identifier per page, and for docs.gitlab.com, the page identifier +Disqus uses an identifier per page, and for <https://docs.gitlab.com>, the page identifier is configured to be the page URL. Therefore, when we change the document location, we need to preserve the old URL as the same Disqus identifier. @@ -181,9 +181,9 @@ Every GitLab instance includes the documentation, which is available at `/help` (`https://gitlab.example.com/help`). For example, <https://gitlab.com/help>. There are [plans](https://gitlab.com/groups/gitlab-org/-/epics/693) to end this -practice and instead link out from the GitLab application to docs.gitlab.com URLs. +practice and instead link out from the GitLab application to <https://docs.gitlab.com> URLs. -The documentation available online on docs.gitlab.com is continuously +The documentation available online on <https://docs.gitlab.com> is continuously deployed every hour from the `master` branch of GitLab, Omnibus, and Runner. Therefore, once a merge request gets merged, it will be available online on the same day. However, they will be shipped (and available on `/help`) within the milestone assigned @@ -195,7 +195,7 @@ available online on 2018-09-15, but, as the feature freeze date has passed, if the MR does not have a "pick into 11.3" label, the milestone has to be changed to 11.4 and it will be shipped with all GitLab packages only on 2018-10-22, with GitLab 11.4. Meaning, it will only be available under `/help` from GitLab -11.4 onwards, but available on docs.gitlab.com on the same day it was merged. +11.4 onwards, but available on <https://docs.gitlab.com/archives/> on the same day it was merged. ### Linking to `/help` @@ -271,7 +271,7 @@ For example, [GitLab.com's `/help`](https://gitlab.com/help). ## Docs site architecture See the [Docs site architecture](site_architecture/index.md) page to learn -how we build and deploy the site at [docs.gitlab.com](https://docs.gitlab.com) and +how we build and deploy the site at <https://docs.gitlab.com> and to review all the assets and libraries in use. ### Global navigation @@ -301,7 +301,7 @@ You will need to push a branch to those repositories, it doesn't work for forks. The `review-docs-deploy*` job will: -1. Create a new branch in the [gitlab-docs](https://gitlab.com/gitlab-org/gitlab-docs) +1. Create a new branch in the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) project named after the scheme: `$DOCS_GITLAB_REPO_SUFFIX-$CI_ENVIRONMENT_SLUG`, where `DOCS_GITLAB_REPO_SUFFIX` is the suffix for each product, e.g, `ce` for CE, etc. diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 2fd3cb06a37..c3bbf86492f 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -564,7 +564,7 @@ Inside the document: ### Remove image shadow -All images displayed on docs.gitlab.com have a box shadow by default. +All images displayed on the [GitLab Docs site](https://docs.gitlab.com) have a box shadow by default. To remove the box shadow, use the image class `.image-noshadow` applied directly to an HTML `img` tag: @@ -598,7 +598,7 @@ You can link any up-to-date video that is useful to the GitLab user. > [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/472) in GitLab 12.1. -GitLab docs (docs.gitlab.com) support embedded videos. +The [GitLab docs site](https://docs.gitlab.com) supports embedded videos. You can only embed videos from [GitLab's official YouTube account](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg). @@ -634,7 +634,7 @@ leave a blank line here leave a blank line here ``` -This is how it renders on docs.gitlab.com: +This is how it renders on the GitLab Docs site: <div class="video-fallback"> See the video: <a href="https://www.youtube.com/watch?v=enMumwvLAug">What is GitLab</a>. @@ -693,6 +693,10 @@ use the following markup for highlighting. _Note that the alert boxes only work for one paragraph only. Multiple paragraphs, lists, headers, etc will not render correctly. For multiple lines, use blockquotes instead._ +Alert boxes only render properly on the GitLab Docs site (<http://docs.gitlab.com>). +Within GitLab itself, they will appear as plain markdown text (like the examples +above the rendered versions, below). + ### Note Notes catch the eye of most readers, and therefore should be used very sparingly. @@ -717,7 +721,7 @@ NOTE: **Note:** This is something to note. ``` -How it renders in docs.gitlab.com: +How it renders on the GitLab Docs site: NOTE: **Note:** This is something to note. @@ -729,7 +733,7 @@ TIP: **Tip:** This is a tip. ``` -How it renders in docs.gitlab.com: +How it renders on the GitLab Docs site: TIP: **Tip:** This is a tip. @@ -741,7 +745,7 @@ CAUTION: **Caution:** This is something to be cautious about. ``` -How it renders in docs.gitlab.com: +How it renders on the GitLab Docs site: CAUTION: **Caution:** This is something to be cautious about. @@ -753,7 +757,7 @@ DANGER: **Danger:** This is a breaking change, a bug, or something very important to note. ``` -How it renders in docs.gitlab.com: +How it renders on the GitLab Docs site: DANGER: **Danger:** This is a breaking change, a bug, or something very important to note. @@ -766,7 +770,7 @@ For highlighting a text within a blue blockquote, use this format: > This is a blockquote. ``` -which renders in docs.gitlab.com to: +which renders on the [GitLab Docs site](https://docs.gitlab.com) as: > This is a blockquote. @@ -1154,7 +1158,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "title= ``` The above example is run by and administrator and will add an SSH public key -titled ssh-key to user's account which has an id of 25. +titled `ssh-key` to user's account which has an id of 25. #### Escape special characters |