Contributor's Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides instructions and best practices for contributing to the Datadog documentation. The repository contains markdown content that is published to the Datadog documentation site using the Hugo static site generator. Contributions are encouraged, and this guide outlines the necessary workflows, style conventions, and technical requirements to ensure consistency and quality.
The documentation covers a wide range of topics, from general content edits to creating new integrations. Following these guidelines helps streamline the review process and maintain a high standard for all published materials.
Sources: README.md:3-5, CONTRIBUTING.md:3-6
Getting Started
The easiest way to contribute a small change is directly from the documentation site. Most pages feature an Edit button that links to the corresponding source file in this GitHub repository, allowing for edits directly through the GitHub web interface.
For more substantial contributions, you will need to follow the specific workflows detailed below, which differ for external contributors and Datadog employees.
Sources: README.md:9-12
Contribution Workflows
There are two primary workflows for contributing, depending on your affiliation with Datadog.
Sources: README.md:16-17, README.md:29-30
This diagram illustrates the two main contribution paths.
Sources: README.md:18-25, README.md:31-44, CLAUDE.md:43-46
External Contributors
If you are not a Datadog employee, follow these steps:
- Fork the
masterbranch of theDataDog/documentationrepository. - Make your desired changes in your forked repository.
- Commit your changes and open a pull request back to the
DataDog/masterbranch. - The Datadog Documentation team is automatically added as a reviewer. A team member may retitle your PR with a
[DOCS-xxxx]ticket number for internal tracking. No action is required from you when this happens.
Sources: README.md:18-25
Datadog Staff
Datadog employees must follow a specific process to ensure CI/CD pipelines run correctly and generate preview builds.
- Branching: Always create a new branch from
master. Never commit directly tomaster. - Branch Naming: You MUST name your branch using the format
<name>/<description>. The forward slash (/) is critical. Without it, the GitLab pipeline will not run, no branch preview will be generated, and the PR will fail CI checks. Using a Slack username for<name>ensures you receive build notifications. - Pull Requests: When ready, create a pull request to
master. Use GitHub's "draft pull request" feature for work in progress. - Preview: A GitHub bot will post a link to a preview of your documentation changes once the build completes.
This flowchart shows the required branching and PR process for Datadog staff.
Sources: README.md:31-44, CLAUDE.md:43-48
Documentation Style Guide
All contributions must adhere to the documentation style guide. The goal is to produce clear, concise, and consistent content. A Vale linter is configured to check for some of these rules automatically in pull requests.
Sources: CONTRIBUTING.md:3-8
General Principles
- Be direct and specific: Use simple phrasing.
- Be objective: Avoid marketing language; focus on clear instructions.
- Be concise: Rephrase complex sentences to be simpler.
- Be empathetic: Avoid words like "easy" or "simply," as user experiences vary.
- Be imperative: Use command-based instructions (e.g., "Configure this thing.") rather than suggestions ("You can configure...").
Sources: CONTRIBUTING.md:15-40
Language and Wording
- Language: Use American English (
en_US). Do not contribute directly to translated files (fr,ja,ko,es), as they are managed by a translation service. - Voice: Use active voice. (e.g., "The Agent receives metrics" instead of "Metrics are sent to the Agent").
- Pronouns: Avoid first-person pronouns ("we", "our"). Use second-person ("you", "your") where appropriate, but sparingly.
- Tense: Describe the present state of the product. Avoid temporal words like "currently" or "will".
- Inclusive Language: Use inclusive terms (e.g., "primary/secondary" instead of "master/slave").
Sources: CONTRIBUTING.md:10-13, CONTRIBUTING.md:52-82
The following table lists words to avoid and their preferred alternatives.
| Word to avoid | Workaround |
|---|---|
| Refer to/visit | Use "see" or "read" when preceding a link. |
| Once | Use "after" to clarify causal relationships. |
| A number of | Be more specific: "a few", "several", "many". |
| [in the] Datadog app | Use "[in] Datadog". |
| Utilize | Use "use". |
| Create a new... | Use "Create a...". |
Sources: CONTRIBUTING.md:86-95
Formatting
Consistent formatting is key to readability.
Headers
Use title case for <h1> and sentence case for all other header levels.
| Level | Case |
|---|---|
<h1> / # Header | Title Case |
<h2> / ## Header | Sentence case |
<h3> / ### Header | Sentence case |
<h4> / #### Header | Sentence case |
<h5> / ##### Header | Sentence case |
<h6> / ###### Header | Sentence case |
Sources: CONTRIBUTING.md:121-130
Text Formatting
Use text formatting to clarify content.
| Formatting | Rule | Example |
|---|---|---|
`code` | Use for code-related content within a sentence. | Use the foo parameter. |
**bold** | Use for UI elements users interact with. | Click Settings. |
*italics* | Use when introducing a product for the first time on a landing page. | The Datadog Agent runs on your hosts... |
Sources: CONTRIBUTING.md:152-158
Links
Use reference-style links with descriptive text. Avoid vague link text like "here".
- Recommended:
read the [Getting Started with Azure][1]with a reference[1]: /getting_started/azure/at the bottom. - Not recommended:
read the [Getting Started with Azure](/getting_started/azure/)
Sources: CONTRIBUTING.md:136-146
Code Substitution
For placeholders in code blocks that are not meant to be used literally, use the format <DATADOG_API_KEY>.
Sources: CONTRIBUTING.md:118-119, content/en/developers/integrations/check_references.md:27-28
Contributing an Integration
Technology Partners and other developers can create and submit integrations to appear on the Datadog Integrations page or Marketplace.
Sources: content/en/developers/integrations/build_integration.md:10
Integration Submission Process
The following diagram outlines the high-level process for submitting a new integration.
Required Assets
A new integration requires several asset files that define its metadata, configuration, and behavior.
| Asset File | Description |
|---|---|
manifest.json | Defines operating parameters, positioning, and metadata for the integration tile. Includes classifier_tags to categorize the integration. |
conf.yaml.example | An example configuration file with init_config (global) and instances (specific) sections. It uses @param specifications for documentation. |
metadata.csv | Describes all metrics collected by the integration, including metric_name, metric_type, unit_name, and description. Required for integrations. |
service_check.json | Describes the service checks performed by the integration, including the check name, statuses (ok, warning, critical), and description. |
| Dashboards/Monitors | JSON files for out-of-the-box dashboards and monitors, located in assets/dashboards and assets/monitors directories. |
| Logos | SVG files for light and dark modes, located in the assets/logos directory. |
README.md | Includes an overview, setup instructions, and data collection details for the integration. |
Sources: layouts/shortcodes/integration-assets.en.md, content/en/developers/integrations/check_references.md:13-14, content/en/developers/integrations/check_references.md:52-54, content/en/developers/integrations/check_references.md:80-82, content/en/developers/integrations/check_references.md:99-101
Configuration File (conf.yaml.example)
The example configuration file documents available parameters using a specific comment-based format. Required parameters are uncommented, while optional ones are commented out.
## @param <name> - <type> - required|optional [- default: <defval>]
## <DESCRIPTION LINE 1>
#
<KEY>: <VALUE>
@paramcommand: Describes a configuration parameter with its name, type, and whether it's required or optional.- Placeholders: Use the format
<THIS_IS_A_PLACEHOLDER>. - Block Comments: Start with
##and should be indented.
Sources: content/en/developers/integrations/check_references.md:18-40
Local Development
While optional for most contributions, running the build locally is possible. The project uses a combination of Hugo, Node.js, and Python.
- Hugo: The static site generator.
- Node.js: Used for package management (
yarn), build automation, and asset processing. - Python: Used for content processing and fetching integration data.
- Makefile: Orchestrates complex build processes.
Key commands for local development include:
yarn startormake start: Full build and runs the development server.make dependencies: Installs all Node.js, Python, and external repository dependencies.yarn build: Creates a production build.
Sources: README.md:42-44, CLAUDE.md:7-27