<!--
title: Follow documentation conventions
domain: observability
topic: Documentation
language: Markdown
source: grafana/grafana
updated: 2025-07-01
url: https://awesomereviewers.com/reviewers/grafana-follow-documentation-conventions/
-->

{% raw %}
Ensure documentation adheres to established style guidelines and technical standards:

1. **Use proper terminology and formatting:**
   - Write "data source" as two words, not "datasource"
   - Maintain proper capitalization for technical acronyms (e.g., "API" not "api")
   - Use consistent language in UI descriptions (prefer "display" over "show")

2. **Avoid possessives with product names:**
   ```
   // Incorrect
   Grafana's dashboard features allow users to visualize data.
   Then we can use the following query for our graph panel.
   
   // Correct
   The dashboard features in Grafana allow users to visualize data.
   To call this stored procedure from a graph panel, use the following query.
   ```

3. **Use appropriate linking syntax:**
   - For same-page references:
     ```
     [Supported Resources](#supported-resources)
     ```
   - For project pages, use Hugo shortcodes instead of ref: syntax:
     ```
     {{< relref "./path/to/page" >}}
     ```

4. **Handle deprecated features properly:**
   - Don't mention removed options in documentation
   - Provide clear alternatives for deprecated functionality
   - Add breaking change notices when documenting removed features
{% endraw %}
