Documentation is very important to the Vector project! This document covers the process of documenting Vector from a contributor's perspective. All Vector contributors are responsible for maintaining Vector's documentation in tandem with code changes.
As a Vector contributor you are responsible for coupling the following user experience related changes with your code:
- Reference docs changes located in the
/website/cuefolder (generally configuration changes) - Existing guide changes located in the
/website/contentfolder - If relevant, highlighting your change for future release notes
By default, you are not responsible for:
- Writing new guides related to your change (unless assigned)
- Writing a blog post on your change (unless assigned)
Vector's reference documentation serves as
a referential index for all things Vector. For example, it contains a
comprehensive list of options
available in Vector's configuration. It's very data-centric and, as a result,
is driven by structured data defined in the /website/cue
directory. CUE is a declarative configuration language
suitable for complex data definitions.
Cue can be installed from package managers,
however it may be necessary to install it from source in order to use the correct
version that Vector depends on. Currently Vector is using v0.7.0. Using a CUE
version different than this may result in CUE check/build errors. We are aiming
to improve the developer experience around external tool dependencies (#15909).
Much of Vector's reference documentation is automatically compiled from source code (e.g., doc comments). To regenerate this content, run:
make generate-component-docsVector has some CUE-related CI checks that are run whenever changes are made to
the docs directory. This includes checks to make sure that the CUE sources are
properly formatted. To run CUE's autoformatting, first install cue,
then run this command from the vector root:
cue fmt ./website/**/*.cueIf that rewrites any files, make sure to commit your changes or else you'll see CI failures.
In addition to proper formatting, the CUE sources need to be valid, that is, the provided data needs to conform to various CUE schemas. To check the validity of the CUE sources:
make check-docsA good practice for writing CUE is to make small, incremental changes and to frequently check to ensure that those changes are valid. If you introduce larger changes that introduce multiple errors, you may have difficulty interpreting CUE's verbose (and not always super helpful) log output. In fact, we recommend using a tool like watchexec to validate the sources every time you save a change:
# From the root
watchexec "make check-docs"Contributors do not need to maintain a changelog. This is automatically generated
via the make release command, made possible by the use of
conventional commit titles.
Because Vector releases often contain many different changes, we use highlights
to surface high-value, meaningful changes. Highlights are markdown files located
in the docs/content/en/highlights folder that
thoughtfully describe a feature. Each highlight is prominently displayed in the
relevant release notes.
It should offer meaningful value to users. This is inherently subjective, and it is impossible to define exact rules for this distinction. But we should be cautious not to dilute the meaning of a highlight by producing low values highlights. Typically, a release contains no more than 6 highlights.
Highlights are not blog posts. They are short one, maybe two, paragraph announcements. Highlights should allude to, or link to, a blog post if relevant.
For example, this adaptive concurrency announcement is noteworthy, but also deserves an in-depth blog post covering the work that resulted in the performance and reliability benefit.