Documentation style guide

This guide defines writing style, capitalization, and grammar rules for Infrahub documentation. As a general rule, prefer consistency and simplicity when possible. For anything not answered below, reference the Microsoft Style Guide.

General tips:

• Avoid words like easy, just, or simple to describe how to do something or how "easy" a task is.

• If a sentence looks too long, it probably is. Try and simplify it or break it into multiple sentences.
• Avoid jargon unless you are sure the reader knows the term.
• Don't hesitate to link between pages and concepts.
• Avoid repeating information when possible, and instead link out to topic or reference pages.

Infrahub terminology

Capitalize nouns that represent first-class, named Infrahub capabilities with defined behavior and APIs. Do not capitalize generic industry concepts, even when Infrahub produces or uses them.

Generators

Always capitalize when referring to the Infrahub feature.

Generator is not a widely established industry term. In Infrahub, a Generator is a named system concept with specific semantics (idempotent, service-model-driven, graph-aware).

Usage	Correct	Incorrect
Feature reference	"Infrahub Generators convert service models into objects."	"Infrahub generators convert..."
Plural	"Configure your Generators in the repository."	"Configure your generators..."

Transformations

Always capitalize when referring to the Infrahub feature. Use "transform" only as a verb, never as a noun.

While "transformation" is a common word, Infrahub Transformations have a specific execution model, defined inputs (GraphQL queries), and defined outputs (artifacts).

Usage	Correct	Incorrect
Feature reference	"Transformations convert graph data into artifacts."	"transformations convert..."
As a verb	"Use this to transform data into vendor formats."	"Use this Transform to..."
Noun form	"Create a Transformation for configuration generation."	"Create a transform for..."

Never use "transform" or "transforms" as a noun. Always use "Transformation" or "Transformations".

Artifacts

Do NOT capitalize unless it starts a sentence or is at the beginning of a bullet point where other items are also capitalized.

Artifact is a broadly accepted industry term. Infrahub artifacts are not conceptually novel in the same way Generators or Transformations are.

Usage	Correct	Incorrect
Mid-sentence	"The artifact is stored in object storage."	"The Artifact is stored..."
Start of sentence	"Artifacts are generated automatically."	"artifacts are generated..."
In a capitalized list	"- Artifacts: Generated outputs..."	"- artifacts: Generated outputs..." (if other items start capitalized)

Profiles

Always capitalize when referring to the Infrahub feature.

Usage	Correct	Incorrect
Feature reference	"Infrahub Profiles allow you to..."	"Infrahub profiles allow..."
Plural	"Create Profiles for your devices."	"Create profiles for..."

Resource Manager

Always capitalize and always use singular form.

Usage	Correct	Incorrect
Feature reference	"Use Resource Manager to allocate IPs."	"Use Resource Managers..."
Plural context	"Configure Resource Manager instances."	"Configure Resource Managers."

Quick reference table

Term	Capitalize?	Notes
Generator(s)	Yes	Infrahub-specific primitive
Transformation(s)	Yes	First-class capability (noun form)
transform	No	Verb only
artifact(s)	No	Generic industry term (capitalize at sentence/list start)
Profile(s)	Yes	Infrahub-specific feature
Resource Manager	Yes	Always singular, system-level capability

Language

We use American English for most standard text. Unique technical terms are included below, or in the Microsoft A-Z word list.

Trailing commas

Use a trailing comma when listing multiple items. This is commonly known as the Oxford comma or serial comma.

❌ Don't do this: There are devices, organizations, and users.

✅ Do this: There are devices, organizations, and users.

Headings and titles

Headings and titles should capitalize the first word only and end with no punctuation. The exception being any proper noun.

❌ Don't do this: Getting Started!

✅ Do this: Getting started

Every page should have a top-level heading. Additional heading tiers can only exist if a higher tier has been used.

❌ Don't do this:

<!-- This is missing an h2 -->
# Page title

### Smaller heading

Avoid over-capitalization

It is tempting to want to capitalize all feature names. Unless the term is a named marketing feature, avoid capitalization.

❌ Don't do this: Git Repository, API Server, User Management

✅ Do this: Git repository, API server, user management

Lists

Capitalize the first letter of each list item. If an item is a complete sentence, give it a period at the end. If it's not, it is okay to omit punctuation. The Microsoft Style Guide has a good explanation of how to handle list punctuation.

When listing items and descriptions, prefer the use of a colon (:) instead of a dash (-).

<!-- Don't do this -->
- Not - this
- Or - this

<!-- Do this -->
- Do: this
- And: this

Bullet point lists

When a word appears at the start of a bullet point in a list where other items begin with capitalized words, capitalize it for consistency.

Correct:

- **Caching**: Generated artifacts are stored...
- **Traceability**: Past values remain available...
- **Peer Review**: Artifacts are automatically part of...
- **Database**: Artifact nodes are stored...

Incorrect:

- **Caching**: Generated artifacts are stored...
- **Traceability**: Past values remain available...
- **Peer Review**: artifacts are automatically part of...  <!-- Should be capitalized -->
- **Database**: artifact nodes are stored...               <!-- Should be capitalized -->

Link text in lists

When a word appears as link text at the start of a bullet point in a list where other items begin with capitalized words, capitalize it.

Correct:

- [Version control](version-control): Understand how branches work...
- [Schema](schema): Learn about data models...
- [Artifacts](artifact): Explore generated outputs...
- [Generators](generator): Learn about code generation...

Incorrect:

- [Version control](version-control): Understand how branches work...
- [Schema](schema): Learn about data models...
- [artifacts](artifact): Explore generated outputs...  <!-- Should be capitalized -->
- [generators](generator): Learn about code generation...  <!-- Should be capitalized -->

Colons

Avoid extra spaces before a colon.

<!-- Don't do this -->
Feature : Explanation of feature

<!-- Do this -->

Feature: Explanation of feature

Code blocks

When creating a code block or snippet with three backticks, make sure to include a language designation.

```shell
this is a shell script
```

Marking code items

Sometimes you need to mention a function or ModelName. To do so, use the inline code backticks in markdown.

Excalidraw diagrams

You can attach .excalidraw diagrams to visually explain concepts, workflows, or processes within the documentation.

warning

Always save Excalidraw files with the "Embed Scene" option checked to maintain the ability to edit in VS Code.

Use i.e. for examples

Prefer i.e. over e.g. or ex.. In a sentence, i.e. is surrounded by commas.

For example: Select the current branch, i.e., 'main'.

It's also acceptable and clearer to use "for example" or "such as".

Product and technology names

Always use correct capitalization for these terms:

• Ansible
• Docker, DockerHub
• Git
• GitHub, GitLab, GitPod
• Grafana
• GraphQL
• InfluxDB
• Infrahub
• Jinja2
• K3s, K8s, Kubernetes
• Linux
• MacOS
• MySQL
• Neo4j
• NGINX
• Node.js
• OpenAPI, OpenConfig
• OpsMill
• PostgreSQL
• Prometheus
• Python
• RabbitMQ
• Terraform
• Ubuntu
• VS Code

Additional terms can be found in .vale/styles/Infrahub/branded-terms-case-swap.yml.