.ai/principles/distilled/documentation-topics.md
line-length (MD013) rule).Troubleshooting, not Troubleshooting merge requests).Internal analytics architecture, not Internal analytics - Architecture).Widgets, Object migration).Overview, Introduction, Use cases, or How it works as concept topic titles; use a specific noun or <noun> workflow instead.active verb + noun structure for task topic titles (e.g., Create an issue).active verb + noun and provide context (e.g., Create an issue when you want to track bugs or future work).To create an issue:).Administrator access. when only admins can perform the task.Prerequisites as plural, even when the list has only one item.You must have:) or a list of verbs (implying You must:); DO NOT use phrases like Ensure that or You must have.infinitive + noun titles.To <verb> a <noun>, you can also [use the API](link.md).Pipeline settings, Administrator options).Important notes or Limitations as reference topic titles; move that content near where it belongs, or use Known issues if necessary.Troubleshooting <feature>, name the file <feature>_troubleshooting.md, use Troubleshooting only in the left nav, and nest it under the feature in the navigation file.Error: or Warning:; use an ellipsis (...) to shorten long messages; DO NOT use links in the title; keep titles under 70 characters (do not disable the line-length markdownlint rule).> [!warning]
> Commands that change data can cause damage if not run correctly or under the right conditions.
> Always run commands in a test environment first and have a backup instance ready to restore.
Tutorial: followed by an active verb (e.g., Tutorial: Create a website).Tutorial:) in the left nav, in quotes; DO NOT abbreviate it.Tutorial in the title on the Learn GitLab with tutorials landing page._index.md in a subfolder under doc/tutorials/; add a link to the tutorial on one of the landing pages.gitlab_base.FutureTense Vale rule to avoid false positives).stage: Tutorials and group: Tutorials metadata when the tutorial content does not align with a single group.guide shortcode to create a stylized ordered list within each section.Get started with <topic_name> for the page title and Getting started for the left nav entry.doc/user/get_started/; DO NOT create a subfolder for each file.For more information area at the end of each step, not inline in body content.Manage your infrastructure).cards shortcode.description metadata to list 3–4 features linked from the page (this text appears on the GitLab documentation home page).FeatureName glossary as the glossary topic title; DO NOT use alternatives such as Terminology, Glossary of terms, or Definitions.active verb + noun structure for prompt example page titles (e.g., Refactor legacy code).How to [do something], Using GitLab Duo for [task], Tips and tricks, or generic titles as prompt example titles.[descriptive_name] format for all prompt placeholders (e.g., [ClassName], [file_path]); DO NOT use vague placeholders like [name] or [thing].Detailed analysis identifying 3-5 specific improvement areas with code examples), not vague (e.g., Analysis of the code).Verify section.Refer to the authoritative sources for examples of how to structure documentation:
For the full picture, see: