Vector documentation conventions

The Vector documentation uses the following conventions. It's important all documenters follow a consistent style to productive cohesive documentation. Documentation is very important to Vector since it is a significant piece of the user experience.

The sections are ordered by generality and designed to be progressive. General section at the top, specific sections at the bottom.



When specifying option types, if the type is enclosed with [ ] symbols then this denotes a list or array. For example:






Option description.

[string] in the above example is an array, or list, of strings.


Required Variables

Within code samples, if word is enclosed with < > symbols, this is a variable and it is required. For example:

type = "s3"

The entire <sink-id> variable must be replaced.

Optional Variables

Within code sample, if a word is enclosed with [< >] symbols, this is a variable and it is optional. For example:

vector --debug [<sink-id>]

The entire [<sink-id>] variable is optional.


Enumerations represent a finite list of acceptable values that are represented with the following syntax:

{"value1" | "value2" }

This can be extended entire variables:

inputs = ["{<source-id> | <transform-id>}"]

In this case, the <source-id> or <transform-id> must be supplied.


Configuration Examples

All sources, transforms, and sinks must include comprehensive configuration examples. This means all options must be represented. The example should be formatted as follows:

# REQUIRED - General
inputs = ["{<source-id> | <transform-id>}"] # not relevant for sources
type = "<type>"
<key> = <value>
# OPTIONAL - General
<key> = <value>
# OPTIONAL - <category>
<key> = <value>
  • Options should be grouped into sections.

  • Options should be sorted alphabetically unless options being at the top are

    descriptive. Ex: the inputs and type options should be at the top.

  • Required sections must be at the top.

  • Tables must be at the bottom since this would otherwise be invalid TOML.


  • Lines should not exceed 80 characters in width unless formatting prohibits it.

  • All documents should have an H1 heading.


  • H1s and H2s should titleize every word. Ex: This Is A Title

  • H3s should titleize only the first word. Ex: This is a title


Images are preferred in the SVG format since it is scalable. If SVG is not possible then PNG is preferred.

Image source files, such as templates, should be included in the assets/source directory. If possible, you should use these source files to create diagrams and images as it keeps a consistent theme.


JSON documents should be presented in javascript code format (since our documentation system does not have a JSON format). "..." should be used to represent variable string values.

Avoid saying "click here", instead, you should turn the relevant word(s) into a link. For example:


When displaying options, a table must adhere to the following format:




\ - \





  • <name> is the name of the option.

  • <type> is one of the supported types, typically a TOML type.

  • <description> succinctly describes what the variable does. A more in-depth description should be moved to a separate section and linked.

  • <tag> is one or more short descriptive tags, such as required, default: 123, etc.

Sources, Transforms, & Sinks


The heading must include the appropriate diagram highlighting the component with a succinct description of what the component does. It should mention the event types that it accepts.

Section Hierarchy

Source, transform, and sink pages must be structured to include the following section hierarchy. The root level represents an h1, children are h2, and so on:

  • Configuration File - A configuration example that includes all options, formatted appropriately.

  • Options - A table representing the available options, formatted appropriately.

  • Examples - The data type accepted as input, must link to the appropriate type in the Data Model document.

  • How It Works

    • Context - Any keys added to the event that represent context (such as "host").

    • Guarantees - The guarantee a source or sink can achieve.

  • Resources - A list of linked resources, such as source code, issues, and so on.


Vectors documentation is organized in a specific manner. Outside of the obvious sections defined in the, there are logical rules that dictate where a document should be placed. The following sections describe those rules.


Within the "Usage" category is a Guides section. Guides are not replacements for documentation on the topic they are covering, they are supplemental tutorials or walkthroughs. For example, monitoring is covered under the Administration section, but we should also offer a monitorig guide that provides a full walk through with specific integrations.


Factual Tone

Vector's documentation tone is factual and academic. Convey subject matter in a clear, concise, and confident manner.

Avoid using vague language such as “it seems” or “probably.” Instead of:

It seems like every SSL reseller packs their certs in a slightly different way with slightly different filenames.


SSL resellers use a variety of naming conventions when packaging certs.

Second Person Narrative

The second-person point of view uses "you" to address the reader. It works well in technical documentation because it focuses on the reader and enables you to use the imperative mood. Avoid using “I” or “we” (the first-person point of view).

Instead of relating your personal experiences to the reader:

Based on our own experience managing remote assets, we created the foo gem so you can transparently upload your static assets to S3 on deploy.

Present concepts based on their own merits:

The foo gem enables you to upload static assets transparently at deploy time.

Present Tense

Use the present tense whenever possible. Phrases such as "was created" indicate unnecessary use of the past tense. Instead of:

This guide was created to describe the characteristics of a well-written Vector article.


This guide describes the characteristics of a well-written Vector article.

Similarly, avoid unnecessary use of the future tense. Instead of:

After you log in, the registration dialog will appear.


After you log in, the registration dialog appears.

Best Practices

  • Link to other internal documents when possible. You can do this by highlighting the word and using ctrl+k to search for and link to a document.

  • If in the same section you only need to link the first occurrence of the word, do not link every single occurrence.

  • When linking to documents, try to link to the specific section.

Shallow Scope

When writing a document put yourself in the shoes of a user coming from a search engine and landing on that page for the first time. They do not have any preconceived knowledge of Vector; they do not know Vector's terms, patterns, or rules. Because of this, documentation should be shallow, explicit, and clear. Users should not have to jump around to obtain the full scope of a document. If a document does require advanced knowledge of another topic you should preface the document with that, and link to the document covering that topic.

Here a few examples to help illustrate this point:

  • Every source, transform, and sink includes all options, even if they are foundational options that are shared and repeated across all components. This avoids the need for a user to have to jump around to separate pages to get the full scope of options available to them.

  • All of the aws_* sources and sinks include an "Authentication" section that repeats the same language. This is easier for the user since it is contained in the relevant integration page. The user should not have to jump to a separate "AWS Authentication" page unless this subject deserves it's own entire document. Even then, each aws_* source and sink should include a link to that document.