- Tutorials: technical content provided step-by-step on how to do things, or how to reach very specific objectives
-[GitLab University](university/README.md): guides to learn Git and GitLab
-**[Topics](topics/)**: indexes pages organized per topic, gathering all resources already published by GitLab related to an specific subject or theme, including:
through courses and videos.
- General Docs
- Technical Articles
- Blog Posts
- Video Tutorials
## User documentation
## User documentation
...
@@ -82,7 +78,4 @@ All technical content published by GitLab lives in the documentation, including:
...
@@ -82,7 +78,4 @@ All technical content published by GitLab lives in the documentation, including:
## Contributor documentation
## Contributor documentation
-[Development](development/README.md) All styleguides and explanations how to contribute.
-[Development](development/README.md) All styleguides and explanations how to contribute.
-[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.
-[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
-[SQL Migration Style Guide](migration_style_guide.md) for creating safe SQL migrations
-[Testing standards and style guidelines](testing.md)
-[Testing standards and style guidelines](testing.md)
-[UX guide](ux_guide/index.md) for building GitLab with existing CSS styles and elements
-[UX guide](ux_guide/index.md) for building GitLab with existing CSS styles and elements
@@ -18,7 +18,7 @@ They are topic-related documentation, written with an user-friendly approach and
...
@@ -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.
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
#### 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 >
...
@@ -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.
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.
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.
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
...
@@ -65,8 +65,8 @@ Use the [writing method](https://about.gitlab.com/handbook/product/technical-wri
## Documentation style guidelines
## Documentation style guidelines
All the documentation follow the same [styleguide](doc_styleguide.html).
All the docs follow the same [styleguide](doc_styleguide.md).
### Markdown
### 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.
