diff options
Diffstat (limited to 'doc/development/documentation/topic_types')
| -rw-r--r-- | doc/development/documentation/topic_types/concept.md | 15 | ||||
| -rw-r--r-- | doc/development/documentation/topic_types/index.md | 2 |
2 files changed, 10 insertions, 7 deletions
diff --git a/doc/development/documentation/topic_types/concept.md b/doc/development/documentation/topic_types/concept.md index e01b06c2c07..66af8780b9b 100644 --- a/doc/development/documentation/topic_types/concept.md +++ b/doc/development/documentation/topic_types/concept.md @@ -10,8 +10,8 @@ A concept introduces a single feature or concept. A concept should answer the questions: -- What is this? -- Why would you use it? +- **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. @@ -24,12 +24,15 @@ Concepts should be in this format: ```markdown # Title (a noun, like "Widgets") -A paragraph that explains what this thing is. +A paragraph or two that explains what this thing is and why you would use it. -Another paragraph that explains what this thing is. +If you start to describe another concept, stop yourself. +Each concept should be about **one concept only**. -Remember, if you start to describe about another concept, stop yourself. -Each concept should be about one concept only. +If you start to describe **how to use the thing**, stop yourself. +Task topics explain how to use something, not concept topics. + +Do not include links to related tasks. The navigation provides links to tasks. ``` ## Concept topic titles diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md index 964b41303cb..cfc231c268a 100644 --- a/doc/development/documentation/topic_types/index.md +++ b/doc/development/documentation/topic_types/index.md @@ -28,7 +28,7 @@ If inline links are not sufficient, you can create a topic called **Related topi and include an unordered list of related topics. This topic should be above the Troubleshooting section. ```markdown -# Related topics +## Related topics - [Configure your pipeline](link-to-topic). - [Trigger a pipeline manually](link-to-topic). |