diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-01-27 06:14:06 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-01-27 06:14:06 +0300 |
commit | 88b04d72ad0c923a084d36177c65a836471605f4 (patch) | |
tree | 6b74c377df81e84ab522268ce34b216203412b64 /doc/development/documentation | |
parent | d1b37847993d744e3d23bee54072020c5258c26b (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/development/documentation')
5 files changed, 102 insertions, 111 deletions
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 776e5aefd00..1f3bb5c375c 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -68,7 +68,7 @@ Adhere to the [Documentation Style Guide](styleguide/index.md). If a style stand ## Folder structure and files -See the [Structure](styleguide/index.md#structure) section of the [Documentation Style Guide](styleguide/index.md). +See the [Folder structure](site_architecture/folder_structure.md) page. ## Metadata diff --git a/doc/development/documentation/site_architecture/folder_structure.md b/doc/development/documentation/site_architecture/folder_structure.md new file mode 100644 index 00000000000..e960a6491c7 --- /dev/null +++ b/doc/development/documentation/site_architecture/folder_structure.md @@ -0,0 +1,98 @@ +--- +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/#assignments +--- + +# Folder structure for documentation + +The documentation is separated by top-level audience folders [`user`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/user), +[`administration`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/administration), +and [`development`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/development) +(contributing) folders. + +Beyond that, we primarily follow the structure of the GitLab user interface or +API. + +Our goal is to have a clear hierarchical structure with meaningful URLs like +`docs.gitlab.com/user/project/merge_requests/`. With this pattern, you can +immediately tell that you are navigating to user-related documentation about +Project features; specifically about Merge Requests. Our site's paths match +those of our repository, so the clear structure also makes documentation easier +to update. + +Put files for a specific product area into the related folder: + +| Directory | Contents | +|:----------------------|:------------------| +| `doc/user/` | Documentation for users. Anything that can be done in the GitLab user interface goes here, including usage of the `/admin` interface. | +| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. Administrator settings in the GitLab user interface are under `doc/user/admin_area/`. | +| `doc/api/` | Documentation for the API. | +| `doc/development/` | Documentation related to the development of GitLab, whether contributing code or documentation. Related process and style guides should go here. | +| `doc/legal/` | Legal documents about contributing to GitLab. | +| `doc/install/` | Instructions for installing GitLab. | +| `doc/update/` | Instructions for updating GitLab. | +| `doc/topics/` | Indexes per topic (`doc/topics/topic_name/index.md`): all resources for that topic. | + +## Work with directories and files + +When working with directories and files: + +1. When you create a new directory, always start with an `index.md` file. + Don't use another filename and do not create `README.md` files. +1. Do not use special characters and spaces, or capital letters in file + names, directory names, branch names, and anything that generates a path. +1. When creating or renaming a file or directory and it has more than one word + in its name, use underscores (`_`) instead of spaces or dashes. For example, + proper naming would be `import_project/import_from_github.md`. This applies + to both image files and Markdown files. +1. For image files, do not exceed 100KB. +1. Do not upload video files to the product repositories. + [Link or embed videos](../styleguide/index.md#videos) instead. +1. There are four main directories: `user`, `administration`, `api`, and + `development`. +1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`, + `profile/`, `dashboard/` and `admin_area/`. + - `doc/user/project/` should contain all project related documentation. + - `doc/user/group/` should contain all group related documentation. + - `doc/user/profile/` should contain all profile related documentation. + Every page you would navigate under `/profile` should have its own document, + for example, `account.md`, `applications.md`, or `emails.md`. + - `doc/user/dashboard/` should contain all dashboard related documentation. + - `doc/user/admin_area/` should contain all administrator-related + documentation describing what can be achieved by accessing the GitLab + administrator interface (not to be confused with `doc/administration` where + server access is required). + - Every category under `/admin/application_settings/` should have its + own document located at `doc/user/admin_area/settings/`. For example, + the **Visibility and Access Controls** category should have a document + located at `doc/user/admin_area/settings/visibility_and_access_controls.md`. +1. The `doc/topics/` directory holds topic-related technical content. Create + `doc/topics/topic_name/subtopic_name/index.md` when subtopics become necessary. + General user and administrator documentation should be placed accordingly. +1. The `/university/` directory is *deprecated* and the majority of its documentation + has been moved. + +If you're unsure where to place a document or a content addition, this shouldn't +stop you from authoring and contributing. Use your best judgment, and then ask +the reviewer of your MR to confirm your decision. You can also ask a technical writer at +any stage in the process. The technical writing team reviews all +documentation changes, regardless, and can move content if there is a better +place for it. + +## Avoid duplication + +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) + +## References across documents + +- Give each folder an `index.md` page that introduces the topic, and both introduces + and links to the child pages, including to the index pages of + any next-level sub-paths. +- To ensure discoverability, ensure each new or renamed doc is linked from its + higher-level index page and other related pages. +- When making reference to other GitLab products and features, link to their + respective documentation, at least on first mention. +- When making reference to third-party products or technologies, link out to + their external sites, documentation, and resources. diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 60894430d15..2f2f60fe66c 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -52,6 +52,8 @@ product, and all together are pulled to generate the docs website: - [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs) - [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc) +Learn more about [the docs folder structure](folder_structure.md). + ## 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 c4dd7132dff..419f7c7fa98 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -181,115 +181,6 @@ included in backticks. For example: - `git clone` is a command, so it must be lowercase, while Git is the product, so it must have a capital G. -## Structure - -We include concept and task topic types in the same larger topic. - -In general, we have one topic that's a landing page. -Below that topic in the left nav are individual topics. Each of these include a concept -and multiple related tasks, reference, and troubleshooting topics. - -### Folder structure overview - -The documentation is separated by top-level audience folders [`user`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/user), -[`administration`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/administration), -and [`development`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/doc/development) -(contributing) folders. - -Beyond that, we primarily follow the structure of the GitLab user interface or -API. - -Our goal is to have a clear hierarchical structure with meaningful URLs like -`docs.gitlab.com/user/project/merge_requests/`. With this pattern, you can -immediately tell that you are navigating to user-related documentation about -Project features; specifically about Merge Requests. Our site's paths match -those of our repository, so the clear structure also makes documentation easier -to update. - -Put files for a specific product area into the related folder: - -| Directory | Contents | -|:----------------------|:------------------| -| `doc/user/` | Documentation for users. Anything that can be done in the GitLab user interface goes here, including usage of the `/admin` interface. | -| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. Administrator settings in the GitLab user interface are under `doc/user/admin_area/`. | -| `doc/api/` | Documentation for the API. | -| `doc/development/` | Documentation related to the development of GitLab, whether contributing code or documentation. Related process and style guides should go here. | -| `doc/legal/` | Legal documents about contributing to GitLab. | -| `doc/install/` | Instructions for installing GitLab. | -| `doc/update/` | Instructions for updating GitLab. | -| `doc/topics/` | Indexes per topic (`doc/topics/topic_name/index.md`): all resources for that topic. | - -### Work with directories and files - -When working with directories and files: - -1. When you create a new directory, always start with an `index.md` file. - Don't use another filename and do not create `README.md` files. -1. Do not use special characters and spaces, or capital letters in file - names, directory names, branch names, and anything that generates a path. -1. When creating or renaming a file or directory and it has more than one word - in its name, use underscores (`_`) instead of spaces or dashes. For example, - proper naming would be `import_project/import_from_github.md`. This applies - to both image files and Markdown files. -1. For image files, do not exceed 100KB. -1. Do not upload video files to the product repositories. - [Link or embed videos](#videos) instead. -1. There are four main directories: `user`, `administration`, `api`, and - `development`. -1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`, - `profile/`, `dashboard/` and `admin_area/`. - - `doc/user/project/` should contain all project related documentation. - - `doc/user/group/` should contain all group related documentation. - - `doc/user/profile/` should contain all profile related documentation. - Every page you would navigate under `/profile` should have its own document, - for example, `account.md`, `applications.md`, or `emails.md`. - - `doc/user/dashboard/` should contain all dashboard related documentation. - - `doc/user/admin_area/` should contain all administrator-related - documentation describing what can be achieved by accessing the GitLab - administrator interface (not to be confused with `doc/administration` where - server access is required). - - Every category under `/admin/application_settings/` should have its - own document located at `doc/user/admin_area/settings/`. For example, - the **Visibility and Access Controls** category should have a document - located at `doc/user/admin_area/settings/visibility_and_access_controls.md`. -1. The `doc/topics/` directory holds topic-related technical content. Create - `doc/topics/topic_name/subtopic_name/index.md` when subtopics become necessary. - General user and administrator documentation should be placed accordingly. -1. The `/university/` directory is *deprecated* and the majority of its documentation - has been moved. - -If you're unsure where to place a document or a content addition, this shouldn't -stop you from authoring and contributing. Use your best judgment, and then ask -the reviewer of your MR to confirm your decision. You can also ask a technical writer at -any stage in the process. The technical writing team reviews all -documentation changes, regardless, and can move content if there is a better -place for it. - -### Avoid duplication - -Do not include the same information in multiple places. -[Link to a single source of truth instead.](#link-instead-of-repeating-text) - -### References across documents - -- Give each folder an `index.md` page that introduces the topic, and both introduces - and links to the child pages, including to the index pages of - any next-level sub-paths. -- To ensure discoverability, ensure each new or renamed doc is linked from its - higher-level index page and other related pages. -- When making reference to other GitLab products and features, link to their - respective documentation, at least on first mention. -- When making reference to third-party products or technologies, link out to - their external sites, documentation, and resources. - -### Structure in documents - -- Include any and all applicable subsections as described on the - [structure and template](../structure.md) page. -- Structure content in alphabetical order in tables, lists, and so on, unless - there's a logical reason not to (for example, when mirroring the user - interface or an otherwise ordered sequence). - ## Language GitLab documentation should be clear and easy to understand. diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 49ad51874e3..ac21010dbad 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -157,7 +157,7 @@ Ensure the following if skipping an initial Technical Writer review: - Specific [user permissions](../../user/permissions.md) are documented. - New documents are linked from higher-level indexes, for discoverability. - The style guide is followed: - - For [directories and files](styleguide/index.md#work-with-directories-and-files). + - For [directories and files](site_architecture/folder_structure.md). - For [images](styleguide/index.md#images). Merge requests that change the location of documentation must always be reviewed by a Technical |