Merge branch 'new-guides-guidelines' into 'master'

New Technical Articles guidelines

Closes gitlab-com/gitlab-docs#89, gitlab-com/gitlab-docs#87, and #29525

See merge request !9984

doc/README.md

-# GitLab Community Edition documentation
+# GitLab Community Edition
 
-## University
+All technical content published by GitLab lives in the documentation, including:
 
-[University](university/README.md) contain guides to learn Git and GitLab through courses and videos.
+- **General Documentation**
+  - [User docs](#user-documentation): general documentation dedicated to regular users of GitLab
+  - [Admin docs](#administrator-documentation): general documentation dedicated to administrators of GitLab instances
+  - [Contributor docs](#contributor-documentation): general documentation on how to develop and contribute to GitLab
+- [Topics](topics/index.md): pages organized per topic, gathering all the
+  resources already published by GitLab related to a specific subject, including
+  general docs, [technical articles](development/writing_documentation.md#technical-articles),
+  blog posts and video tutorials.
+- [GitLab University](university/README.md): guides to learn Git and GitLab
+  through courses and videos.
 
 ## User documentation
 

doc/development/README.md

@@ -12,6 +12,8 @@
   contributing to the API.
 - [Documentation styleguide](doc_styleguide.md) Use this styleguide if you are
   contributing to documentation.
+- [Writing documentation](writing_documentation.md)
+  - [Distinction between general documentation and technical articles](writing_documentation.md#distinction-between-general-documentation-and-technical-articles)
 - [SQL Migration Style Guide](migration_style_guide.md) for creating safe SQL migrations
 - [Testing standards and style guidelines](testing.md)
 - [UX guide](ux_guide/index.md) for building GitLab with existing CSS styles and elements

doc/development/doc_styleguide.md

@@ -3,6 +3,8 @@
 This styleguide recommends best practices to improve documentation and to keep
 it organized and easy to find.
 
+See also [writing documentation](writing_documentation.md).
+
 ## Location and naming of documents
 
 >**Note:**
@@ -27,6 +29,7 @@ The table below shows what kind of documentation goes where.
 | `doc/legal/` | Legal documents about contributing to GitLab. |
 | `doc/install/`| Probably the most visited directory, since `installation.md` is there. Ideally this should go under `doc/administration/`, but it's best to leave it as-is in order to avoid confusion (still debated though). |
 | `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`); Technical Articles: user guides, admin guides, technical overviews, tutorials (`doc/topics/topic-name/`). |
 
 ---
 
@@ -56,6 +59,10 @@ The table below shows what kind of documentation goes where.
          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.
+   Note that `topics` holds the index page per topic, and technical articles. General
+   user- and admin- related documentation, should be placed accordingly.
 
 ---
 

doc/development/writing_documentation.md

+# Writing documentation
+
+  - **General Documentation**: written by the developers responsible by creating features. Should be submitted in the same merge request containing code. Feature proposals (by GitLab contributors) should also be accompanied by its respective documentation. They can be later improved by PMs and Technical Writers.
+  - **Technical Articles**: written by any [GitLab Team](https://about.gitlab.com/team/) member, GitLab contributors, or [Community Writers](https://about.gitlab.com/handbook/product/technical-writing/community-writers/).
+  - **Indexes per topic**: initially prepared by the Technical Writing Team, and kept up-to-date by developers and PMs, in the same merge request containing code.
+
+## Distinction between General Documentation and Technical Articles
+
+### General documentation
+
+General documentation is categorized by _User_, _Admin_, and _Contributor_, and describe what that feature is, what it does, and its available settings.
+
+### Technical Articles
+
+Technical articles replace technical content that once lived in the [GitLab Blog](https://about.gitlab.com/blog/), where they got out-of-date and weren't easily found.
+
+They are topic-related documentation, written with an user-friendly approach and language, aiming to provide the community with guidance on specific processes to achieve certain objectives.
+
+A technical article guides users and/or admins to achieve certain objectives (within guides and tutorials), or provide an overview of that particular topic or feature (within technical overviews). It can also describe the use, implementation, or integration of third-party tools with GitLab.
+
+They live under `doc/topics/topic-name/`, and can be searched per topic, within "Indexes per Topic" pages. The topics are listed on the main [Indexes per Topic](../topics/index.md) page.
+
+#### Types of Technical Articles
+
+- **User guides**: technical content to guide regular users from point A to point B
+- **Admin guides**: technical content to guide administrators of GitLab instances from point A to point B
+- **Technical Overviews**: technical content describing features, solutions, and third-party integrations
+- **Tutorials**: technical content provided step-by-step on how to do things, or how to reach very specific objectives
+
+#### Understanding guides, tutorials, and technical overviews
+
+Suppose there's a process to go from point A to point B in 5 steps: `(A) 1 > 2 > 3 > 4 > 5 (B)`.
+
+A **guide** can be understood as a description of certain processes to achieve a particular objective. A guide brings you from A to B describing the characteristics of that process, but not necessarily going over each step. It can mention, for example, steps 2 and 3, but does not necessarily explain how to accomplish them.
+
+- Live example: "GitLab Pages from A to Z - [Part 1](../user/project/pages/getting_started_part_one.md) to [Part 4](../user/project/pages/getting_started_part_four.md)"
+
+A **tutorial** requires a clear **step-by-step** guidance to achieve a singular objective. It brings you from A to B, describing precisely all the necessary steps involved in that process, showing each of the 5 steps to go from A to B.
+It does not only describes steps 2 and 3, but also shows you how to accomplish them.
+
+- Live example (on the blog): [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/)
+
+A **technical overview** is a description of what a certain feature is, and what it does, but does not walk
+through the process of how to use it systematically.
+
+- Live example (on the blog): [GitLab Workflow, an overview](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/)
+
+#### Special format
+
+Every **Technical Article** contains, in the very beginning, a blockquote with the following information:
+
+- A reference to the **type of article** (user guide, admin guide, tech overview, tutorial)
+- A reference to the **knowledge level** expected from the reader to be able to follow through (beginner, intermediate, advanced)
+- A reference to the **author's name** and **GitLab.com handle**
+
+```md
+> **Type:** tutorial ||
+> **Level:** intermediary ||
+> **Author:** [Name Surname](https://gitlab.com/username)
+```
+
+#### Technical Articles - Writing Method
+
+Use the [writing method](https://about.gitlab.com/handbook/product/technical-writing/#writing-method) defined by the Technical Writing team.
+
+## Documentation style guidelines
+
+All the docs follow the same [styleguide](doc_styleguide.md).
+
+### Markdown
+
+Currently GitLab docs use Redcarpet as [markdown](../user/markdown.md) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future.

doc/topics/index.md

+# Topics
+
+Welcome to Topics! We have organized our content resources into topics
+to get you started on areas of your interest. Each topic page
+consists of an index listing all related content. It will guide
+you through better understanding GitLab's concepts
+through our regular docs, and, when available, through articles (guides,
+tutorials, technical overviews, blog posts) and videos.
+
+- [GitLab Installation](../install/README.md)
+- [Continuous Integration (GitLab CI)](../ci/README.md)
+- [GitLab Pages](../user/project/pages/index.md)
+
+>**Note:**
+Non-linked topics are currently under development and subjected to change.
+More topics will be available soon.

doc/user/project/pages/getting_started_part_four.md

 # GitLab Pages from A to Z: Part 4
 
+> **Type**: user guide || 
+> **Level**: intermediate || 
+> **Author**: [Marcia Ramos](https://gitlab.com/marcia)
+
 - [Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md)
 - [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md)
 - [Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md)

doc/user/project/pages/getting_started_part_one.md

 # GitLab Pages from A to Z: Part 1
 
+> **Type**: user guide || 
+> **Level**: beginner || 
+> **Author**: [Marcia Ramos](https://gitlab.com/marcia)
+
 - **Part 1: Static sites and GitLab Pages domains**
 - [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md)
 - [Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md)

doc/user/project/pages/getting_started_part_three.md

 # GitLab Pages from A to Z: Part 3
 
+> **Type**: user guide || 
+> **Level**: beginner || 
+> **Author**: [Marcia Ramos](https://gitlab.com/marcia)
+
 - [Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md)
 - [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md)
 - **Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates**

doc/user/project/pages/getting_started_part_two.md

 # GitLab Pages from A to Z: Part 2
 
+> **Type**: user guide || 
+> **Level**: beginner || 
+> **Author**: [Marcia Ramos](https://gitlab.com/marcia)
+
 - [Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md)
 - **Part 2: Quick start guide - Setting up GitLab Pages**
 - [Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md)