diff options
Diffstat (limited to 'doc/development/documentation/topic_types')
5 files changed, 329 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`. diff --git a/doc/development/documentation/topic_types/index.md b/doc/development/documentation/topic_types/index.md new file mode 100644 index 00000000000..af3e66fe87a --- /dev/null +++ b/doc/development/documentation/topic_types/index.md @@ -0,0 +1,130 @@ +--- +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 +--- + +# 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: + +- [Concept](concept.md) +- [Task](task.md) +- [Reference](reference.md) +- [Troubleshooting](troubleshooting.md) + +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. + +## Other topic types + +In addition to the four primary topic types, we have a few other types. + +### Related topics + +If inline links are not sufficient, you can create a topic called **Related topics** +and include an unordered list of related topics. This topic should be above the Troubleshooting section. + +```markdown +# Related topics + +- [Configure your pipeline](link-to-topic). +- [Trigger a pipeline manually](link-to-topic). +``` + +### Tutorials + +A tutorial is page that contains an end-to-end walkthrough of a complex workflow or scenario. +In general, you might consider using a tutorial when: + +- The workflow requires a number of sequential steps where each step consists + of sub-steps. +- The steps cover a variety of GitLab features or third-party tools. + +Tutorials are learning aids that complement our core documentation. +They do not introduce new features. +Always use the primary [topic types](#documentation-topic-types-ctrt) to document new features. + +Tutorials should be in this format: + +```markdown +# Title (starts with "Tutorial:" followed by an active verb, like "Tutorial: Create a website") + +A paragraph that explains what the tutorial does, and the expected outcome. + +To create a website: + +1. [Do the first task](#do-the-first-task) +1. [Do the second task](#do-the-second-task) + +Prerequisites (optional): + +- Thing 1 +- Thing 2 +- Thing 3 + +## Do the first task + +To do step 1: + +1. First step. +1. Another step. +1. Another step. + +## Do the second task + +Before you begin, make sure you have [done the first task](#do-the-first-task). + +To do step 2: + +1. First step. +1. Another step. +1. Another step. +``` + +### Get started + +A get started page is a set of steps to help a user get set up +quickly to use a single GitLab feature or tool. +It consists of more than one task. + +Get started pages should be in this format: + +```markdown +# Title ("Get started with <feature>") + +Complete the following steps to ... . + +1. First step. +1. Another step. +1. Another step. + +If you need to add more than one task, +consider using subsections for each distinct task. +``` + +In the left nav, use `Get started` as the text. On the page itself, spell out +the full name. For example, `Get started with application security`. + +### Topics and resources + +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. + +## Heading text guidelines + +In general, for heading text: + +- Be clear and direct. Make every word count. +- Use articles and prepositions. +- Follow [capitalization](../styleguide/index.md#capitalization) guidelines. +- Do not repeat text from earlier headings. For example, if the page is about merge requests, + instead of `Troubleshooting merge requests`, use only `Troubleshooting`. + +See also [guidelines for headings in Markdown](../styleguide/index.md#headings-in-markdown). diff --git a/doc/development/documentation/topic_types/reference.md b/doc/development/documentation/topic_types/reference.md new file mode 100644 index 00000000000..42f4f5f6f94 --- /dev/null +++ b/doc/development/documentation/topic_types/reference.md @@ -0,0 +1,32 @@ +--- +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 +--- + +# Reference topic type + +Reference information should be in an easily-scannable format, +like a table or list. It's similar to a dictionary or encyclopedia entry. + +```markdown +# Title (a noun, like "Pipeline settings" or "Administrator options") + +Introductory sentence. + +| Setting | Description | +|---------|-------------| +| **Name** | Descriptive sentence about the setting. | +``` + +## Reference headings + +Reference headings are usually nouns. + +Avoid these heading titles: + +- `Important notes`. Instead, incorporate this information + closer to where it belongs. For example, this information might be a prerequisite + for a task, or information about a concept. +- `Limitations`. Instead, move the content near other similar information. + If you must, you can use the title `Known issues`. diff --git a/doc/development/documentation/topic_types/task.md b/doc/development/documentation/topic_types/task.md new file mode 100644 index 00000000000..3488cb90cf9 --- /dev/null +++ b/doc/development/documentation/topic_types/task.md @@ -0,0 +1,65 @@ +--- +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 +--- + +# Task topic type + +A task gives instructions for how to complete a procedure. + +Tasks should be in this format: + +```markdown +# Title (starts with an active verb, like "Create a widget" or "Delete a widget") + +Do this task when you want to... + +Prerequisites (optional): + +- Thing 1 +- Thing 2 +- Thing 3 + +To do this task: + +1. Location then action. (Go to this menu, then select this item.) +1. Another step. +1. Another step. + +Task result (optional). Next steps (optional). +``` + +Here is an example. + +```markdown +# Create an issue + +Create an issue when you want to track bugs or future work. + +Prerequisites: + +- You must have at least the Developer role for the project. + +To create an issue: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues > List**. +1. In the top right corner, select **New issue**. +1. Complete the fields. (If you have reference content that lists each field, link to it here.) +1. Select **Create issue**. + +The issue is created. You can view it by going to **Issues > List**. +``` + +## Task headings + +For the heading text, use the structure `active verb` + `noun`. +For example, `Create an issue`. + +If you have several tasks on a page that share prerequisites, you can use the title +`Prerequisites` and link to it. + +## Related topics + +- [View the format for writing task steps](../styleguide/index.md#navigation). diff --git a/doc/development/documentation/topic_types/troubleshooting.md b/doc/development/documentation/topic_types/troubleshooting.md new file mode 100644 index 00000000000..35187bd892e --- /dev/null +++ b/doc/development/documentation/topic_types/troubleshooting.md @@ -0,0 +1,56 @@ +--- +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 +--- + +# Troubleshooting topic type + +Troubleshooting topics should be the last topics on a page. + +If a page has more than five troubleshooting topics, put the content on a separate page that has troubleshooting information exclusively. Name the page `Troubleshooting <feature>` +and in the left nav, use the word `Troubleshoot` only. + +Troubleshooting can be one of three types. + +## An introductory topic + +This topic introduces the troubleshooting section of a page. +For example: + +```markdown +## Troubleshooting + +When working with <x feature>, you might encounter the following issues. +``` + +## Troubleshooting task + +The title should be similar to a [standard task](task.md). +For example, "Run debug tools" or "Verify syntax." + +## Troubleshooting reference + +This topic includes the error message. For example: + +```markdown +### The error message or a description of it + +You might get an error that states <error message>. + +This issue occurs when... + +The workaround is... +``` + +If multiple causes or workarounds exist, consider putting them into a table format. +If you use the exact error message, surround it in backticks so it's styled as code. + +## Troubleshooting headings + +For the heading of a **Troubleshooting reference** topic: + +- Consider including at least a partial error message. +- Use fewer than 70 characters. + +If you do not put the full error in the title, include it in the body text. |