diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-07-20 15:40:28 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-07-20 15:40:28 +0000 |
commit | b595cb0c1dec83de5bdee18284abe86614bed33b (patch) | |
tree | 8c3d4540f193c5ff98019352f554e921b3a41a72 /doc/development/documentation | |
parent | 2f9104a328fc8a4bddeaa4627b595166d24671d0 (diff) | |
download | gitlab-ce-b595cb0c1dec83de5bdee18284abe86614bed33b.tar.gz |
Add latest changes from gitlab-org/gitlab@15-2-stable-eev15.2.0-rc42
Diffstat (limited to 'doc/development/documentation')
5 files changed, 47 insertions, 11 deletions
diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index 1f270a2b5ee..92c34c01e5d 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -66,7 +66,8 @@ Supported attributes: | `attribute` | datatype | **{dotted-circle}** No | Detailed description. | | `attribute` | datatype | **{dotted-circle}** No | Detailed description. | -Response body attributes: +If successful, returns [`<status_code>`](../../api/index.md#status-codes) and the following +response attributes: | Attribute | Type | Description | |:-------------------------|:---------|:----------------------| @@ -103,7 +104,10 @@ for the section. For example: > `widget_message` [introduced](<link-to-issue>) in GitLab 14.3. ``` -## Attribute deprecation +## Deprecations + +To document the deprecation of an API endpoint, follow the steps to +[deprecate a page or topic](versions.md#deprecate-a-page-or-topic). To deprecate an attribute: @@ -121,8 +125,8 @@ To deprecate an attribute: | `widget_name` | string | **{dotted-circle}** No | [Deprecated](<link-to-issue>) in GitLab 14.7 and is planned for removal in 15.4. Use `widget_id` instead. The name of the widget. | ``` -1. Optional. To widely announce the change, or if it's a breaking change, - [update the deprecations and removals documentation](../deprecation_guidelines/#update-the-deprecations-and-removals-documentation). +To widely announce a deprecation, or if it's a breaking change, +[update the deprecations and removals documentation](../deprecation_guidelines/#update-the-deprecations-and-removals-documentation). ## Method description @@ -151,6 +155,14 @@ For information about writing attribute descriptions, see the [GraphQL API descr ## Response body description +Start the description with the following sentence, replacing `status code` with the +relevant [HTTP status code](../../api/index.md#status-codes), for example: + +```markdown +If successful, returns [`200 OK`](../../api/index.md#status-codes) and the +following response attributes: +``` + Use the following table headers to describe the response bodies. Attributes should always be in code blocks using backticks (`` ` ``). diff --git a/doc/development/documentation/site_architecture/folder_structure.md b/doc/development/documentation/site_architecture/folder_structure.md index e960a6491c7..0e8065d794f 100644 --- a/doc/development/documentation/site_architecture/folder_structure.md +++ b/doc/development/documentation/site_architecture/folder_structure.md @@ -85,6 +85,15 @@ place for it. Do not include the same information in multiple places. [Link to a single source of truth instead.](../styleguide/index.md#link-instead-of-repeating-text) +For example, if you have code in a repository other than the [primary repositories](index.md#architecture), +and documentation in the same repository, you can keep the documentation in that repository. + +Then you can either: + +- Publish it to <https://docs.gitlab.com>. +- Link to it from <https://docs.gitlab.com> by adding an entry in the global navigation. + View [an example](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fedb6378a3c92274ba3b6031df0d34455594e4cc/content/_data/navigation.yaml#L2944). + ## References across documents - Give each folder an `index.md` page that introduces the topic, and both introduces diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 05015fe7c5f..af24fbe303b 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -59,6 +59,19 @@ product, and all together are pulled to generate the docs website: Learn more about [the docs folder structure](folder_structure.md). +### Documentation in other repositories + +If you have code and documentation in a repository other than the [primary repositories](#architecture), +you should keep the documentation with the code in that repository. + +Then you can either: + +- [Add the repository to the list of products](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/development.md#add-a-new-product) + published at <https://docs.gitlab.com>. +- [Add an entry in the global navigation](global_nav.md#add-a-navigation-entry) for + <https://docs.gitlab.com> that links to the documentation in that repository. + View [an example](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fedb6378a3c92274ba3b6031df0d34455594e4cc/content/_data/navigation.yaml#L2944-L2946). + ## Assets To provide an optimized site structure, design, and a search-engine friendly diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 700d64c30d1..1af0cb72055 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -49,7 +49,7 @@ GitLab adds all troubleshooting information to the documentation, no matter how unlikely a user is to encounter a situation. GitLab Support maintains their own -[troubleshooting content](../../../administration/index.md#support-team-docs) +[troubleshooting content](../../../administration/index.md#support-team-documentation) in the GitLab documentation. ### The documentation includes all media types @@ -1096,14 +1096,15 @@ copy of `https://gitlab.com/gitlab-org/gitlab`, run in a terminal: ### Animated images -Sometimes an image with animation (such as an animated GIF) -can help the reader understand a complicated interaction with the user interface. +Avoid using animated images (such as animated GIFs). They can be distracting +and annoying for users. -However, you should use them sparingly and avoid them when you can. -Do not use them to replace written descriptions of processes or the product. +If you're describing a complicated interaction in the user interface and want to +include a visual representation to help readers understand it, you can: -If you include an animated image, follow the same size and naming conventions we use for images. If the animated image loops, add at least a three -second pause to the end of the loop. +- Use a static image (screenshot) and if necessary, add callouts to emphasize an + an area of the screen. +- Create a short video of the interaction and link to it. ## Videos diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index feb10845aea..d55cbe28d9b 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -361,6 +361,7 @@ To configure Vale in your editor, install one of the following as appropriate: - Sublime Text [`SublimeLinter-contrib-vale` package](https://packagecontrol.io/packages/SublimeLinter-contrib-vale). - Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). You can configure the plugin to [display only a subset of alerts](#show-subset-of-vale-alerts). +- Atom [`atomic-vale` package](https://atom.io/packages/atomic-vale). - Vim [ALE plugin](https://github.com/dense-analysis/ale). - JetBrains IDEs - No plugin exists, but [this issue comment](https://github.com/errata-ai/vale-server/issues/39#issuecomment-751714451) |