Merge branch 'master' of gitlab.com:gitlab-org/gitlab-ce into docs-pages-introdocs-pages-intro

2 files changed, 48 insertions, 55 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 c0386290785..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,
@@ -28,41 +27,43 @@ a test that will fail if it spots a new `README.md` file.
 
 ### Markdown
 
-The [documentation website](https://docs.gitlab.com) had its markdown engine migrated from [Redcarpet to GitLab Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108)
-in October 2018.
+The [documentation website](https://docs.gitlab.com) uses GitLab Kramdown as its Markdown rendering engine [as of October 2018](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108). For a complete Kramdown reference, see the [GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/).
 
 The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown)
 gem will support all [GFM markup](../../user/markdown.md) in the future. For now,
-use regular markdown markup, following the rules on this style guide. For a complete
-Kramdown reference, check the [GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/).
-Use Kramdown markup wisely: do not overuse its specific markup (e.g., `{:.class}`) as it will not render properly in
-[`/help`](index.md#gitlab-help).
+use regular markdown markup, following the rules in the linked style guide. 
+
+Note that Kramdown-specific markup (e.g., `{:.class}`) will not render properly in on GitLab instances in [`/help`](index.md#gitlab-help).
 
 ## Content
 
 These guidelines help toward the goal of having every user's search of documentation
 yield a useful result, and ensuring content is helpful and easy to consume.
 
-- What to include:
-  - Any and all helpful information, processes, and tips for implementing,
-  using, and troubleshooting GitLab features. [The documentation is the single source of truth](https://about.gitlab.com/handbook/documentation/#documentation-as-single-source-of-truth-ssot)
-  for this information.
-  - 'Risky' or niche problem-solving steps. There is no reason to withhold these or
-  store them elsewhere; simply include them along with the rest of the docs including all necessary
-  detail, such as specific warnings and caveats about potential ramifications.
-  - Any content types/sources, if relevant to users or admins. You can freely
-  include presentations, videos, etc.; no matter who it was originally written for,
-  if it is helpful to any of our audiences, we can include it. If an outside source
-  that's under copyright, rephrase, or summarize and link out; do not copy and paste.
-  - All applicable subsections as described on the [structure and template](structure.md) page,
-  with files organized in the [correct directory](index.md#documentation-directory-structure).
+### Subject matter
+
+[The documentation is the single source of truth (SSOT)](https://about.gitlab.com/handbook/documentation/#documentation-as-single-source-of-truth-ssot) for any and all helpful information and processes needed to learn about, implement, use, and troubleshoot GitLab features. Note that this includes problem-solving actions that may address rare cases or be considered 'risky', so long as proper context is provided. See the SSOT link for more detail.
+
+### Media types and sources
+
+Include any media types/sources, if relevant to readers. You can freely include or link presentations, diagrams, videos, etc.; no matter who it was originally composed for, if it is helpful to any of our audiences, we can include it.
+
+   - If you use an image that has a separate source file (for example, a vector or diagram format), link the image to the source file so that it may be reused or updated by anyone.
+   - Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source.
+
+### Structure across documents
+
+- 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.
+
+### Structure within documents
+
+- Include any and all applicable subsections as described on the [structure and template](structure.md) page,
 - To ensure discoverability, link to each doc from its higher-level index page and other related pages.
-- 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.
-- Do not duplicate information.
 - Structure content in alphabetical order in tables, lists, etc., unless there is
-  a logical reason not to (for example, when mirroring the UI or an ordered sequence).
+  a logical reason not to (for example, when mirroring the UI or an otherwise ordered sequence).
 
 ## Language