blob: e01b06c2c0723d513bd3e7a517aa68c285236885 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
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/product/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 you 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 topic titles
For the title 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 topic 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`.
|
