Contributing to the Documentation

We welcome any contributions to our documentation repository, dvc.org. Contributions can be updates to the documentation content, or (rare) changes to the JS engine we use to run the website.

In case of a minor change, you can use the Edit on GitHub button to open the source code page. Use the Edit button (pencil icon) to edit the file in-place, and then Commit changes from the bottom of the page.

Structure of the project

To contribute documentation, these are the relevant locations:

Content (content/docs/): Markdown files. One file — one page of the documentation.
Images (static/img/): Add new images (.png, .svg, etc.) here. Use them in Markdown files like this: ![](/img/<filename>.gif).
Navigation (content/docs/sidebar.json): Edit it to add or change entries in the navigation sidebar.

Merging the appropriate changes to these files into the main branch is enough to update the docs and redeploy the website.

Submitting changes

Find or open a new issue in the issue tracker to let us know that you are working on this.
Format the source code by following the style guidelines below. We highly recommend setting up a development environment as explained below. Among other things, it can help format the documentation and JS code automatically.
Push the changes to your fork of dvc.org and submit a PR to the upstream repo.

We will review your PR as soon as possible. Thank you for contributing!

Development environment

We highly recommend running this web app locally to check documentation changes before submitting them, and it's quite necessary when making changes to the website engine itself. Source code and content files need to be properly formatted and linted as well, which is also ensured by the full setup below.

Make sure you have a recent LTS version of Node.js (>=18.0.0, <=20.x), and install Yarn:

In Windows, you may need to install Visual Studio Build Tools, and the [Windows

SDK] first.

$ npm install -g yarn

Having cloned this project locally, navigate into the directory and install the project dependencies with Yarn:

$ yarn

Launch the server locally with:

$ yarn develop

This will start the server on the default port, 8000. Visit http://localhost:8000/ and navigate to the page in question. This will also enable the pre-commit Git hook that will be formatting and linting your code and documentation files automatically.

All commands

These Node scripts are specified in the docs repo's package.json file.

To build the project and run it:

yarn develop - run development server with hot reload.
yarn build - build assets in the public directory.
yarn start - run production static server over the public directory.

All the tests, formatting, and linters below will be automatically enforced before every commit with Husky and lint-staged before each commit, as well as with GitHub Actions upon submitting PRs.

If you change source code files, run tests:

yarn test - run tests.

We use Prettier to format our source code. Below is a set of wrapper commands for your convenience:

yarn format-all - Run prettier --write on all files to find formatting issues and automatically fix as many as possible.
yarn format-check-all - Run prettier --check on all files, exiting with an error if any issues are found. This is particularly useful for CI.
yarn format-staged - alias for lint-staged, which will run all applicable linters on all files staged in your copy of the git repository.
yarn format <file> - Run prettier on a specific file.

We use linters (e.g. ESLint) to check source code style and detect different errors:

yarn lint - run eslint on all compatible source code files: js, jsx, ts, tsx, json.
yarn lint-fix - use eslint --fix to automatically fix as many issues as possible.
yarn lint-ts - uses tsc to attempt to compile the project, ensuring all TypeScript types are properly formatted.
yarn lint-css - lint .css files with stylelint, which covers more than prettier does alone.

To use the fix variant of all of these tools in one command, use yarn fix-all.

Note that you can always use the formatter or linter directly (e.g. yarn eslint <file> or yarn prettier --check <file>).

ENV variables

Some environment variables are required to deploy this project to production, others can be used to debug the project. Please check the production system settings to see all the variables that production and deployment system depend on.

Some available variables:

GA_ID – ID of the Google Analytics counter.
ANALYZE - boolean property to run webpack-analyzer.
SENTRY_DSN - Sentry URL for errors tracking.

Doc style guidelines (JavaScript and Markdown)

Some of the following rules are applied automatically by a pre-commit Git hook that is installed when yarn runs (see dev env).

No trailing white spaces are allowed.
Text content must be properly formatted at 80 symbols width.

💡 We recommend using Visual Studio Code with the Rewrap plugin for help with this.
You can see the configuration of our formatter tool (Prettier) here. You may also run the formatting commands manually. (Advanced usage of Prettier is available through yarn prettier ...)
Markdown: Using dvc <command>, the docs engine will create a link to that command automatically. (No need to use []() explicitly to create them.)
Markdown: Using dvc.api.<api_method>() or dvc.api, the docs engine will create a link to that API method automatically. (No need to use []() explicitly to create them.)
Markdown: Bullet lists shouldn't be too long (5-7 items max., ideally).
Markdown: The text in each bullet item also shouldn't be too long (3 sentence paragraphs max.) Full sentence bullets should begin with a capital letter and end in period .. Otherwise, they can be all lower case and have no ending punctuation. Bullets can be separated by an empty line if they contain several paragraphs, but this is discouraged: try to keep items short.
Markdown: Syntax highlighting in fenced code blocks should use the usage dvc, dvctable, yaml, or diff custom languages.
- usage is employed to show the dvc --help output for each command reference.
- dvc can be used to show examples of commands and their output in a terminal session.
- dvctable is used for creating colored, bold, or italic table cells. (You can see an example of dvctable in our "Get Started" section.)
- yaml is used to show samples of DVC files, or other YAML contents.
- diff is used mainly for examples of git diff output.

Check out the .md source code of any command reference to get a better idea, for example in this very file.

General language guidelines

We try to use a casual and fun tone in our docs. We also avoid authoritative language such as "As you can see, clearly this is what happened, of course" etc. which while good-intentioned, may scare readers off.

We prefer general, human-friendly language rather than exact jargon as long as it's correct. Example: avoid Git jargon such as revision or reference, preferring the more basic terms commit or version.

The command reference contains some of our most technical documents where specialized language is used the most, but even there, we use expandable sections for complex implementation details.

Start by writing the essence in simple terms, and complete it with clarifications, edge cases, or other precisions in a separate iteration.

We use bold text for emphasis, and italics for special terms.

We also use "emoji" symbols sparingly for visibility on certain notes. Mainly:

📖 For notes that link to other related documentation
⚠️ Important warnings or disclaimers related to advanced DVC usage
💡 Useful notes and tips, often related to external tools and integrations

Some other emojis currently in use here and there: ⚡ ✅ 🙏 🐛 ⭐ ⚙️ ℹ️ (among others).