Documentation topic types (CTRT) contribute
Each topic on a page should be one of the following topic types:
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 the topic types.
The acronym refers to the first letter of each topic type.
Other page and topic types
In addition to the four primary topic types, you can use the following:
- Page type: Tutorials
- Page type: Get started
- Topic type: Related topics
- Page or topic type: Glossaries
Pages and topics to avoid
You should avoid:
- Pages that are exclusively links to other pages. The only exceptions are top-level pages that aid with navigation.
- Topics that have one or two sentences only. In these cases:
- Incorporate the information in another topic.
- If the sentence links to another page, use a Related topics link instead.
Topic title guidelines
In general, for topic titles:
- Be clear and direct. Make every word count.
- Use fewer than 70 characters when possible. The markdownlint rule:
line-length
(MD013) - Use articles and prepositions.
- Follow capitalization guidelines.
- Do not repeat text from earlier topic titles. For example, if the page is about merge requests,
instead of
Troubleshooting merge requests
, use onlyTroubleshooting
. - Avoid using hyphens to separate information.
For example, instead of
Internal analytics - Architecture
, useInternal analytics architecture
orArchitecture of internal analytics
.
See also guidelines for heading levels in Markdown.
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.
Links in this section should be brief and scannable. They are usually not full sentences, and so should not end in a period.
## Related topics
- [CI/CD variables](link-to-topic.md)
- [Environment variables](link-to-topic.md)
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support