Skip to content

Latest commit

 

History

History
201 lines (135 loc) · 6.31 KB

CONTRIBUTING.md

File metadata and controls

201 lines (135 loc) · 6.31 KB
Raw

Contributing

You can help to improve the Thoth Tech documentation by sending pull requests to this repository. Thank you for your interest and help!

Feel free to make a proposal, we can discuss anything and if we don't agree we'll feel free not to merge it and we'll thank you for caring about it. We want to create a welcoming environment for everyone who is interested in contributing.

Documentation testing

We treat documentation like code. Therefore, we use processes similar to those used for code to maintain standards and quality of documentation.

We have tests:

  • To lint the words and structure of the documentation.

Run tests locally

You can run these tests on your local computer. This has the advantage of speeding up the feedback loop. You can know of any problems with the changes in your branch without waiting for a CI pipeline to run.

To run the tests locally, it's important to:

  • Install the tools
  • Run linters the same way they are run in CI pipelines. It's important to use same configuration we use in CI pipelines, which can be different than the default configuration of the tool.

Local linters

To help adhere to the documentation style guidelines, and improve the content added to documentation, install documentation linters and integrate them with your code editor.

At Thoth Tech, we mostly use:

Prettier

Prettier checks that Markdown syntax follows the CommonMark specifications.

Vale

Vale is a grammar, style, and word usage linter for the English language. Vale's configuration is stored in the .vale.ini file located in the root directory.

Vale supports creating custom tests that extend any of several types of checks, which we store in the .vale/thothtech/ directory in the documentation directory.

Vale result types

Vale returns three types of results:

  • Error - For words or phrases with ambiguous meanings.
  • Warning - For writing style preferences.
  • Suggestion - For basic writing tenets and best practices.
Vale readability score

In ReadingLevel.yml, we have implemented the Flesch-Kincaid grade level test to determine the readability of our documentation.

As a general guideline, the lower the score, the more readable the documentation. For example, a page that scores 12 before a set of changes, and 9 after, indicates an iterative improvement to readability. The score is not an exact science, but is meant to help indicate the general complexity level of the page.

The readability score is calculated based on the number of words per sentence, and the number of syllables per word. For more information, see the Vale documentation.

Installation

Install prerequisites

macOS

  1. Install Homebrew, which is a package manager for macOS that allows you to easily install programs and tools through the Terminal. Visit their website for installation instructions.

  2. Follow the official instructions to install nvm, a Node version manager. Then, run the following to install and use the repository's Node version:

    nvm install
nvm use

    The required Node version should be automatically detected from the .nvmrc file. This can be confirmed by running nvm which.

  3. Install all dependencies

    npm install
Windows (using WSL2)

  1. Set up Windows Subsystem for Linux (WSL) and the Linux distribution. WSL allows Linux distributions to run on the Windows OS. Visit this website for more information.

    wsl --install

  2. Follow instructions for Linux

Linux

  1. Install curl

    sudo apt-get install curl

  2. Follow the official instructions to install nvm, a Node version manager. Then, run the following to install and use the repository's Node version:

    nvm install
nvm use

    The required Node version should be automatically detected from the .nvmrc file. This can be confirmed by running nvm which.

  3. Install all dependencies

    npm install

Install linters

  1. Install prettier:

    npm install

  2. Install vale. To install for:

    • macOS using brew, run: brew install vale.
    • Linux, use your distribution's package manager or a released binary.

These tools can be integrated with your code editor.

Configure editors

Using linters in your editor is more convenient than having to run the commands from the command line.

To configure prettier in your editor, install one of the following as appropriate:

To configure Vale in your editor, install one of the following as appropriate:

Lint checks

The following commands can be run to format all Markdown files across the entire repository:

# Format markdown style (fixing markdown style issues)
npm run format

# Lint markdown style and prose (reporting issues)
npm run lint

# Lint markdown style only
npm run format:check

# Lint prose only
npm run prose:check

Contributing guidelines

Contributing formatting guidelines, including git workflow and commit formatting requirements can be found in our git contribution guide.