Writing and Formatting Content
Relevant source files
The following files were used as context for generating this wiki page:This document outlines the principles, standards, and technical processes for writing and formatting content within the Datadog documentation repository. The project uses the Hugo static site generator with the Goldmark Markdown renderer, which is compliant with CommonMark. All content is written in American English (en_US).
The primary goal is to produce clear, concise, and objective documentation for a technical audience. This involves adhering to specific writing styles, formatting rules, and contribution workflows. The content creation process includes both manual authoring of Markdown files and automated generation of pages, such as the API reference documentation.
Sources: CONTRIBUTING.md:1-12, README.md:3-4, 34-36, CLAUDE.md:5-6
General Principles
Content should be direct, specific, objective, and concise. It's important to be empathetic to the reader by avoiding words like "easy" or "simply" and to treat them as knowledgeable peers. Instructions should be imperative and explicit, providing concrete examples rather than abstract concepts.
Sources: CONTRIBUTING.md:14-49
Language and Voice
- Voice: Use the active voice instead of the passive voice.
- Pronouns: Avoid first-person pronouns ("we", "our"). Use second-person pronouns ("you", "your") when appropriate, but avoid overuse.
- Tense: Describe the present state of the product and avoid temporal words like "currently" or "now".
- Inclusive Language: Use inclusive language, such as "primary/secondary" instead of "master/slave" and "allow list/disallow list" instead of "blacklist/whitelist". Gender-neutral pronouns like "they" and "them" should be used.
Sources: CONTRIBUTING.md:58-99
Wording and Phrases
A set of preferred words and phrases is enforced to maintain consistency. A Vale linter implementation helps enforce these rules during the pull request process.
| 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 with "a few", "several", or "many". |
| [in the] Datadog app | Use "[in] Datadog". |
| Utilize | Use "use". |
| Create a new... | Use "Create a...". |
Sources: CONTRIBUTING.md:101-118
Contribution Workflow
The process for contributing content involves creating a pull request (PR) against the master branch. For Datadog employees, branches must follow a <name>/<description> naming convention to trigger the CI pipeline and generate a preview build.
Sources: README.md:6-32, CLAUDE.md:43-48
The following diagram illustrates the contribution workflow for Datadog employees.
Sources: README.md:20-32, CLAUDE.md:43-48
Formatting Guidelines
Consistent formatting is crucial for readability and is applied across all content types.
Sources: CONTRIBUTING.md:131-132
Text and Headers
Specific markdown syntax is used for emphasis and structure.
| Formatting | Rule | Example |
|---|---|---|
`code` | For code-related content within a sentence. | Use the foo parameter. |
**bold** | For important text, like UI elements. | Click Settings. |
*italics* | For introducing a product on a landing page. | The Datadog Agent runs on your hosts... |
Sources: CONTRIBUTING.md:164-170
Headers follow a specific case convention based on their level.
| 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:138-146
Links and Code
Links should use reference-style formatting with descriptive text. For placeholders in code blocks that are not meant to be literal, the format <DATADOG_API_KEY> must be used.
Sources: CONTRIBUTING.md:134-136, 151-162
Specialized Content
Certain types of content have specific structures and formatting requirements, often involving automated generation or strict file formats.
Integration Assets
Integrations require a set of asset files that define their behavior and appearance in the Datadog platform. These include configuration files, manifests, and metadata.
Sources: content/en/developers/integrations/check_references.md:1-10
The relationship between an integration and its key assets is shown below.
Configuration File (conf.yaml.example)
The example configuration file uses special ## @param annotations to document configuration options. All required parameters must be uncommented, while optional ones are commented out by default.
## @param host - string - required
## The host to connect to.
#
host: <HOST>
## @param port - integer - optional - default: 8080
## The port to connect to.
#
# port: 8080
Sources: content/en/developers/integrations/check_references.md:16-40
Metrics Metadata (metadata.csv)
This file describes all metrics collected by the integration. It has a strict column structure.
| Column name | Mandatory or Optional | Description |
|---|---|---|
metric_name | Mandatory | Name of the metric. |
metric_type | Mandatory | Type of the metric (e.g., gauge, rate). |
orientation | Mandatory | 1 for increasing, 0 for neutral, -1 for decreasing. |
integration | Mandatory | Normalized name of the integration. |
short_name | Mandatory | A human-readable, abbreviated version of the metric name. |
description | Optional | Description of the metric. |
Sources: content/en/developers/integrations/check_references.md:104-124
API Documentation
API documentation pages are not manually written. They are auto-generated from OpenAPI specification files (e.g., full_spec.yaml) located in the assets/api/ directory. A Node.js script, build-api-pages.js, processes these specs to create content.
Sources: assets/scripts/build-api-pages.js:1-10, content/en/api/README.md, CLAUDE.md:33-39
The generation process involves several steps:
- Dereferencing: The script uses
@apidevtools/json-schema-ref-parserto resolve all$refpointers in the YAML spec. - Page Creation: For each tag in the spec, a corresponding Markdown file (
_index.md) is created. - Resource Generation: For each API endpoint, the script generates:
- Example JSON for requests and responses.
- HTML tables detailing the schema of request/response bodies.
- Translation Files: JSON files are created to hold translatable strings like descriptions and summaries.
The following diagram illustrates this automated workflow.
The script contains functions like schemaTable and filterExampleJson to transform the OpenAPI schema into formatted HTML and JSON. For instance, schemaTable recursively builds an HTML table from a JSON schema object, creating nested rows for complex objects.
Sources: assets/scripts/build-api-pages.js:743-780, 526-560
Diagrams with Mermaid.js
Datadog Notebooks and documentation support creating diagrams using Mermaid.js syntax within a Markdown code block. To create a diagram, you specify mermaid as the language for the code block.
Sources: content/en/notebooks/guide/build_diagrams_with_mermaidjs.md:7-14
Here is an example of a simple flowchart:
This feature allows for the creation of flowcharts, sequence diagrams, Gantt charts, and more directly within documentation content.
Conclusion
Writing and formatting content for the Datadog documentation is a structured process governed by a comprehensive style guide and supported by automation. By following the principles of clarity and conciseness, adhering to specific formatting rules for text, code, and specialized assets like integrations, and leveraging automated workflows for API documentation, contributors can create high-quality, consistent, and useful content for Datadog's technical audience. The contribution workflow, centered around pull requests and automated previews, ensures that all content is reviewed and validated before publication.