Vale-based technical documentation style guide

A Vale-compatible style for technical writers documenting open-source software and for anyone writing about Open Source.

Checks

The supplied rules perform the following checks:

• common language usage errors
• punctuation
• editorializing
• wordiness
• terminology
• corporate speak
• inclusive language

Installation on Linux

The following installation procedure has been tested on Linux Mint and openSUSE.

Option 1. Install precompiled binary

1. Check the available tags at https://github.com/errata-ai/vale/tags
2. Use wget to download the latest tag, for example:

wget https://github.com/errata-ai/vale/releases/download/v2.20.0/vale_2.20.0_Linux_64-bit.tar.gz

3. Extract the downloaded archive:

tar xvf vale_2.20.0_Linux_64-bit.tar.gz vale

4. Move the vale binary to the /usr/local/bin directory:

sudo mv ./vale /usr/local/bin

Instead of /usr/local/bin, you can move the binary to any directory that is in $PATH.

Option 2. Install via Brew

1. Install Brew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Vale:

brew install vale

Install the style guide

1. Create the styles directory: mkdir $HOME/styles
2. Clone the Git repository: cd $HOME/styles && git clone https://github.com/openSUSE/suse-vale-styleguide.git

Create configuration file

Create a configuration file in your home directory:

nano $HOME/.vale.ini

Add the following configuration:

StylesPath = styles
MinAlertLevel = suggestion
[asciidoctor]
experimental = YES
[*.{md,txt,adoc}]
BasedOnStyles = suse-vale-styleguide

Save the changes.

Add XML support (openSUSE)

1. Install the libxslt-tools and docbook-xsl-stylesheets packages.
2. Open the .vale.ini file for editing and update the existing configuration as follows:

StylesPath = styles
MinAlertLevel = suggestion
[asciidoctor]
experimental = YES
[*.xml]
Transform = /usr/share/xml/docbook/stylesheet/suse2022-ns/xhtml/docbook.xsl
BasedOnStyles = suse-vale-styleguide
[*.{md,txt,adoc}]
BasedOnStyles = suse-vale-styleguide

3. Save the changes.

Add XML support (Linux Mint)

1. Install the docbook5-xml and docbook-xsl packages.
2. Open the .vale.ini file for editing and update the existing configuration as follows:

StylesPath = styles
MinAlertLevel = suggestion
[asciidoctor]
experimental = YES
[*.xml]
Transform = /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl
BasedOnStyles = suse-vale-styleguide
[*.{md,txt,adoc}]
BasedOnStyles = suse-vale-styleguide

3. Save the changes.

Add VS Code and VSCodium integration

In VS Code, install the Vale +VS Code extension. In VSCodium, install Vale +VS Code extension.

Source code

In VS Code or VSCodium, choose File > Preferences > Settings and specify the path to the Vale binary (for example, /usr/local/bin/vale) under Vale > Vale CLI: Path.

Updating the style guide

Switch to the suse-vale-styleguide directory and run the git pull command.

Problems?

Please report bugs and issues in the Issues section.

Contribute

If you've found an error, or you have a suggestion for improvement, open an issue in the Issues section.

To add a new feature or fix issues yourself, proceed as follows.

1. Fork the project's repository.
2. Create a feature branch using the git checkout -b new-feature command.
3. Add your new feature or fix bugs and run the git commit -am 'Add a new feature' command to commit changes.
4. Push changes using the git push origin new-feature command.
5. Submit a pull request.

License

The GNU General Public License version 3