having unified and well-readable documentation is an important aspect of providing the user of a Julia package to not only get started, but to also use the package throughout. For example there are the Google developer documentation style guide or the Microsoft Writing Style Guide.
In my own experience, these guides are only followed, if a developer (here: myself) is reminded often enough to follow them. I recently added a GitHub action to my Package repository to remember to update the Changelog before merging a PR.

I would like to present a short introduction on how to set up a check for the above style guides using the example of the Google set of rules for your Julia package documentation. This is inspired by the setup of JuMP.jl, where I personally stumbled into this.

Installation and setup.

For the style guides there exists the nice project vale.sh, which can for example be easily installed using homebrew on Mac OS.

After that, we can call vale on terminal, which for example accepts a folder to check all files in.

To setup vale for your documentation, create a docs/.vale.ini in the docs folder. Mine has the following content

StylesPath = styles
MinAlertLevel = warning
Vocab = Manopt

Packages = Google

[*.md]
BasedOnStyles = Vale, Google
TokenIgnores =          \
    \$.+?\$,            \
    \]\(@(ref|id|cite).+?\), \

The first two lines tell vale, that styles are stored in docs/styles, and that we want to see already warnings and not only errors (but not suggestions).

Vocab = Manopt means that in the file docs/styles/Vocab/Manopt/accept.txt we collect (one entry per line) words, especially names, that are not considered errors, mine for example contains

Manifolds.jl
[Mm]anopt(:?.org|.jl)?

such that Manifolds.jl is considered a correct word, as well as manopt both with M and m upfront, and with or without the suffixes .org and .jl – so regular expressions an also be used therein.

We also specify that we want to use the Google package – especially on Markdown files. Within these, we want to ignore math $...$ and documenter style id/ref/cite entries.

Running Vale

With this setup, we can already call vale sync (from within the docs/ folder) for setup, which installs the Google package for the above developer guidelines. after that vale src checks its rules on the files in the docs/src folder, which for us means all Markdown files.

Another possibility is to use the VS Code extension.

Finally, one can add a run of vale for example to the documenter run on CI, since vale also provides several GitHub actions. My documenter.yml contains the step

      - name: "vale.sh spell check"
        uses: errata-ai/vale-action@reviewdog
        with:
          files: docs/src
          fail_on_error: true
          filter_mode: nofilter
          vale_flags: "--config=docs/.vale.ini"

which besides running the same vale src as above also does the vale sync setup before, so there is no need to check in the automatically installed styles like the Google one from this example.

Vale.sh your code files

Besides just the Markdown files in the docs, you can also put the vale.ini into your main folder and adapt it to

StylesPath = docs/styles
MinAlertLevel = warning
Vocab = Manopt

Packages = Google

[*.{md,jl}]
BasedOnStyles = Vale, Google
TokenIgnores =          \
    \$.+?\$,            \
    \]\(@(ref|id|cite).+?\), \

Since Vale 2.30, Julia files can also be checked. To be precise, doc strings, strings, comments are also run through vale. Of course you also have to adapt the CI accordingly.

Summary

The start might take a while to work through ones own documentation and doc strings and follow a style, but I for example learned to avoid i.e. in documentations by now and to unify several styles, like capitalisation of headings even more.