diff options
Diffstat (limited to 'doc/development/documentation/topic_types/concept.md')
-rw-r--r-- | doc/development/documentation/topic_types/concept.md | 46 |
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`. |