Fix links and do some refactoring

4 files changed, 21 insertions, 40 deletions

diff --git a/doc/README.md b/doc/README.md
index f76961b89f9..df11d5e49a8 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -1,4 +1,4 @@
-# GitLab Community Edition Documentation
+# GitLab Community Edition
 
 All technical content published by GitLab lives in the documentation, including:
 
@@ -6,16 +6,12 @@ All technical content published by GitLab lives in the documentation, including:
   - [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
-- **[Technical Articles](development/writing_documentation.md#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
-- **[Topics](topics/)**: indexes pages organized per topic, gathering all resources already published by GitLab related to an specific subject or theme, including:
-  - General Docs
-  - Technical Articles
-  - Blog Posts
-  - Video Tutorials
+- [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
 
@@ -82,7 +78,4 @@ All technical content published by GitLab lives in the documentation, including:
 ## Contributor documentation
 
 - [Development](development/README.md) All styleguides and explanations how to contribute.
-- [Writing documentation](development/writing_documentation.md)
-- [Distinction between General Documentation and Technical Articles](development/writing_documentation.md#distinction-between-general-documentation-and-technical-articles)
-- [GitLab University](university/README.md): guides to learn Git and GitLab through courses and videos.
 - [Legal](legal/README.md) Contributor license agreements.
diff --git a/doc/development/README.md b/doc/development/README.md
index e27e7fc7d19..3c797505aa9 100644
--- a/doc/development/README.md
+++ b/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
diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md
index 54cfd6959d4..482ec54207b 100644
--- a/doc/development/writing_documentation.md
+++ b/doc/development/writing_documentation.md
@@ -18,7 +18,7 @@ They are topic-related documentation, written with an user-friendly approach and
 
 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/) page.
+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
 
@@ -33,7 +33,7 @@ Suppose there's a process to go from point A to point B in 5 steps: `(A) 1 > 2 >
 
 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.html) to [Part 4](../user/project/pages/getting_started_part_one.html)"
+- 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.
@@ -65,8 +65,8 @@ Use the [writing method](https://about.gitlab.com/handbook/product/technical-wri
 
 ## Documentation style guidelines
 
-All the documentation follow the same [styleguide](doc_styleguide.html).
+All the docs follow the same [styleguide](doc_styleguide.md).
 
 ### Markdown
 
-Currently GitLab docs use Redcarpet as [markdown](../user/markdown.html) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future.
+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.
diff --git a/doc/topics/index.md b/doc/topics/index.md
index ef6f68f50d7..6de13d79554 100644
--- a/doc/topics/index.md
+++ b/doc/topics/index.md
@@ -1,30 +1,16 @@
 # Topics
 
-We have organized our content resources into 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 
+you through better understanding GitLab's concepts
 through our regular docs, and, when available, through articles (guides,
 tutorials, technical overviews, blog posts) and videos.
 
-- Idea to Production
-  - [GitLab Installation](../install/README.md)
-  - GitLab Workflow
-    - Chat
-    - Issue
-    - Plan
-    - Code
-    - Commit
-    - Test
-    - Review
-    - Staging
-    - Production
-    - Feedback
-- Authentication
-- [Continuous Integration (GitLab CI)](../ci/)
-- GitLab Flow (branching strategy)
-- [GitLab Pages](../user/project/pages/)
-- Integrations
+- [GitLab Installation](../install/README.md)
+- [Continuous Integration (GitLab CI)](../ci/README.md)
+- [GitLab Pages](../user/project/pages/index.md)
 
-> Note: non-linked indexes are currently under development and subjected to change.
-More indexes will be available along the time.
\ No newline at end of file
+>**Note:**
+Non-linked topics are currently under development and subjected to change.
+More topics will be available soon.