Welcome to mirror list, hosted at ThFree Co, Russian Federation.

gitlab.com/gitlab-org/gitlab-foss.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat (limited to 'doc/development/documentation/topic_types/concept.md')
-rw-r--r--doc/development/documentation/topic_types/concept.md46
1 files changed, 46 insertions, 0 deletions
diff --git a/doc/development/documentation/topic_types/concept.md b/doc/development/documentation/topic_types/concept.md
new file mode 100644
index 00000000000..a20bb93a97f
--- /dev/null
+++ b/doc/development/documentation/topic_types/concept.md
@@ -0,0 +1,46 @@
+---
+stage: none
+group: Style Guide
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Concept topic type
+
+A concept introduces a single feature or concept.
+
+A concept should answer the questions:
+
+- What is this?
+- Why would I use it?
+
+Think of everything someone might want to know if they've never heard of this concept before.
+
+Don't tell them **how** to do this thing. Tell them **what it is**.
+
+If you start describing another concept, start a new concept and link to it.
+
+Concepts should be in this format:
+
+```markdown
+# Title (a noun, like "Widgets")
+
+A paragraph that explains what this thing is.
+
+Another paragraph that explains what this thing is.
+
+Remember, if you start to describe about another concept, stop yourself.
+Each concept should be about one concept only.
+```
+
+## Concept headings
+
+For the heading text, use a noun. For example, `Widgets` or `GDK dependency management`.
+
+If a noun is ambiguous, you can add a gerund. For example, `Documenting versions` instead of `Versions`.
+
+Avoid these heading titles:
+
+- `Overview` or `Introduction`. Instead, use a more specific
+ noun or phrase that someone would search for.
+- `Use cases`. Instead, incorporate the information as part of the concept.
+- `How it works`. Instead, use a noun followed by `workflow`. For example, `Merge request workflow`.