Merge branch 'edits-to-index-of-development-docs' into 'master'

Edits to documentation dev doc index

See merge request gitlab-org/gitlab-ce!27135

2 files changed, 23 insertions, 32 deletions

diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index a4da34a50ce..4a2ff64807e 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -48,29 +48,21 @@ as its markdown rendering engine. See the [GitLab Markdown Guide](https://about.
 
 Adhere to the [Documentation Style Guide](styleguide.md). If a style standard is missing, you are welcome to suggest one via a merge request.
 
-## Documentation directory structure
+## Documentation types and organization
 
 The documentation is structured based on the GitLab UI structure itself,
 separated by [`user`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/user),
 [`administrator`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`contributor`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development).
 
-In order to have a [solid site structure](https://searchengineland.com/seo-benefits-developing-solid-site-structure-277456) for our documentation,
-all docs should be linked. Every new document should be cross-linked to its related documentation, and linked from its topic-related index, when existent.
-
-The directories `/workflow/`, `/gitlab-basics/`, `/university/`, and `/articles/` have
-been **deprecated** and the majority their docs have been moved to their correct location
-in small iterations. Please do not create new docs in these folders. Organize docs by product area and subject, not type.
+Organize docs by product area and subject, not type. For example, do not create groupings of similar media types
+(e.g. indexes of all articles, videos, etc.).
 
-### Documentation files
-
-- When you create a new directory, always start with an `index.md` file.
-  Do not use another file name and **do not** create `README.md` files.
-- **Do not** use special chars and spaces, or capital letters in file names,
-  directory names, branch names, and anything that generates a path.
-- Max screenshot size: 100KB.
-- We do not support videos (yet).
+Similarly, we do not use glossaries or FAQs. Such grouping of content by type makes
+it difficult to browse for the information you need and difficult to maintain up-to-date content.
+Instead, organize content by its subject (e.g. everything related to CI goes together)
+and cross-link between any related content.
 
-### Location and naming documents
+### Location and naming of files
 
 Our goal is to have a clear hierarchical structure with meaningful URLs
 like `docs.gitlab.com/user/project/merge_requests/`. With this pattern,
@@ -78,16 +70,8 @@ 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.
 
-While the documentation is home to a variety of content types, we do not organize by content type.
-For example, do not create groupings of similar media types (e.g. indexes of all articles, videos, etc.).
-Similarly, we do not use glossaries or FAQs. Such grouping of content by type makes
-it difficult to browse for the information you need and difficult to maintain up-to-date content.
-Instead, organize content by its subject (e.g. everything related to CI goes together)
-and cross-link between any related content.
-
-Do not simply link out to GitLab technical blog posts. There should be an up-to-date
-single source of truth on the topic within the documentation, and the top of the
-blog post should be updated to link to that doc.
+In order to have a [solid site structure](https://searchengineland.com/seo-benefits-developing-solid-site-structure-277456) for our documentation,
+all docs should be linked at least from its higher-level index page if not also from other relevant locations.
 
 The table below shows what kind of documentation goes where.
 
@@ -102,13 +86,18 @@ The table below shows what kind of documentation goes where.
 | `doc/update/`         | Same with `doc/install/`. Should be under `administration/`, but this is a well known location, better leave as-is, at least for now.                                                                          |
 | `doc/topics/`         | Indexes per Topic (`doc/topics/topic-name/index.md`): all resources for that topic (user and admin documentation, articles, and third-party docs)                                                              |
 
-**General rules & best practices:**
+**Rules and best practices:**
 
+1. When you create a new directory, always start with an `index.md` file.
+  Do not use another file name and **do not** create `README.md` files.
+1. **Do not** use special chars and spaces, or capital letters in file names,
+  directory names, branch names, and anything that generates a path.
 1. When creating a new document and it has more than one word in its name,
    make sure to use underscores instead of spaces or dashes (`-`). For example,
    a proper naming would be `import_projects_from_github.md`. The same rule
    applies to images.
-1. Start a new directory with an `index.md` file.
+1. For image files, do not exceed 100KB.
+1. We do not yet support embedded videos. Please link out.
 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/`.
@@ -129,6 +118,9 @@ The table below shows what kind of documentation goes where.
 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 admin- related documentation, should be placed accordingly.
+1. The directories `/workflow/`, `/university/`, and `/articles/` have
+been **deprecated** and the majority their docs have been moved to their correct location
+in small iterations.
 
 If you are unsure where a document or a content addition should live, this should
 not stop you from authoring and contributing. You can use your best judgment and
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 69505ed9e67..1cefe48b4c1 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -14,9 +14,8 @@ For programmatic help adhering to the guidelines, see [linting](index.md#linting
 
 ## Files
 
-- [Directory structure](index.md#location-and-naming-documents): place the docs
-  in the correct location.
-- [Documentation files](index.md#documentation-files): name the files accordingly.
+See the [Documentation types and organization](index.md#documentation-types-and-organization) section
+on the index page for information on how to structure and name files across the GitLab documentation.
 
 DANGER: **Attention:**
 **Do not** use capital letters, spaces, or special chars in file names,
@@ -54,7 +53,7 @@ Include any media types/sources, if relevant to readers. You can freely include
 
 ### Structure across documents
 
-- Place files in the correct directory per the [Documentation directory structure](index.md#documentation-directory-structure) guidelines.
+- Place files in the correct directory per the [Documentation directory structure](index.md#documentation-types-and-organization) guidelines.
 - To avoid duplication, do not include the same information in multiple places. Instead, choose one 'single source of truth (SSOT)' location and link from other relevant locations.
 - When referencing other GitLab products and features, link to their respective docs.
 - When referencing third-party products or technologies, link out to their external sites, documentation, and resources.