diff options
Diffstat (limited to 'doc/development/documentation/topic_types')
| -rw-r--r-- | doc/development/documentation/topic_types/concept.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/topic_types/index.md | 13 | ||||
| -rw-r--r-- | doc/development/documentation/topic_types/task.md | 6 |
3 files changed, 13 insertions, 8 deletions
diff --git a/doc/development/documentation/topic_types/concept.md b/doc/development/documentation/topic_types/concept.md index 7be6bef4fad..e01b06c2c07 100644 --- a/doc/development/documentation/topic_types/concept.md +++ b/doc/development/documentation/topic_types/concept.md @@ -11,7 +11,7 @@ A concept introduces a single feature or concept. A concept should answer the questions: - What is this? -- Why would I use it? +- Why would you use it? Think of everything someone might want to know if they've never heard of this concept before. diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md index 8e8c474ce3c..964b41303cb 100644 --- a/doc/development/documentation/topic_types/index.md +++ b/doc/development/documentation/topic_types/index.md @@ -6,20 +6,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Documentation topic types (CTRT) -At GitLab, we have not traditionally used types for our content. However, we are starting to -move in this direction, and we now use four primary topic types: +Each topic on a page should be one of the following topic types: - [Concept](concept.md) - [Task](task.md) - [Reference](reference.md) - [Troubleshooting](troubleshooting.md) +Even if a page is short, the page usually starts with a concept and then +includes a task or reference topic. + The tech writing team sometimes uses the acronym `CTRT` to refer to our topic types. The acronym refers to the first letter of each topic type. -In general, each page in the GitLab documentation contains multiple topics. -Each topic on a page should be recognizable as a specific topic type. - In addition to the four primary topic types, we also have a page type for [Tutorials](tutorial.md) and [Get started](#get-started). @@ -66,9 +65,9 @@ Some pages are solely a list of links to other documentation. We do not encourage this page type. Lists of links can get out-of-date quickly and offer little value to users, who prefer to search to find information. -## Topic text guidelines +## Topic title guidelines -In general, for topic text: +In general, for topic titles: - Be clear and direct. Make every word count. - Use articles and prepositions. diff --git a/doc/development/documentation/topic_types/task.md b/doc/development/documentation/topic_types/task.md index 78d670a16d6..0dba3e079b6 100644 --- a/doc/development/documentation/topic_types/task.md +++ b/doc/development/documentation/topic_types/task.md @@ -69,6 +69,12 @@ For example, `Create an issue when you want to track bugs or future work`. To start the task steps, use a succinct action followed by a colon. For example, `To create an issue:` +## Task prerequisites + +As a best practice, if the task requires the user to have a role other than Guest, +put the minimum role in the prerequisites. See [the Word list](../styleguide/word_list.md) for +how to write the phrase for each role. + ## Related topics - [View the format for writing task steps](../styleguide/index.md#navigation). |