Upgrade your Docs-As-Code Foo with the Vale Text Linter
Tutorial Room | Mon 20 Jan 10:45 a.m.–12:25 p.m.
Presented by
-
Alec Clews
https://alecthegeek.gitlab.io/
Alec wrote his first computer program in 1978 on a mainframe, had his own Internet sub-domain in 1993 (earth.demon.co.uk) running on an MS-DOS PC, and downloaded Linux on three floppy disks from Compuserve in 1993. Eventually the ISP provided webpage hosting, still archived on the Wayback Machine, and you can see his latest attempt at a personal website at https://alecthegeek.gitlab.io/.
More recently he's been working on API documentation and support, and has been discovering how to be more consistent and productive with tools like Vale, Git, Spectral, and Lefthook.
Alec also has a passion for teaching and sharing his knowledge across various communities. From Online Safety for local seniors, Desktop Docker tutorials at LCA Christchurch, and teaching kids at CoderDojo.
Alec Clews
https://alecthegeek.gitlab.io/
Abstract
Writing Good Docs is hard, and getting extra help is welcome.
The [Vale](https://vale.sh) text linter provides automation for the technical writer, in the same way that unit tests and code linters support the software developer.
Specifically Vale allows text to be validated against style guides and custom spelling rules. A set of well regarded style guides are
provided, but projects are free to add their own rules to reflect their specific needs.
After this workshop you should be inspired and be able to easily add Vale to your current project.
This tutorial walks through:
1. How to add Vale to an existing project and using pre-existing style guides
2. Setting up custom spelling rules and dictionaries
3. How to configure Vale for specific file formats and style guides
4. Adding or modifying style guide rules
5. Some of the pitfalls of using reading metrics.
An example project will be provided for students to implement Vale. However feel free to bring your own project in Markdown, reStructuredText, or AsciiDoc.
Before attending the workshop your should install the Vale binary on your machine (see https://vale.sh/docs/vale-cli/installation/) and a text editor. Vale works on Linux, macOS, Windows, and in a container image.
Writing Good Docs is hard, and getting extra help is welcome. The [Vale](https://vale.sh) text linter provides automation for the technical writer, in the same way that unit tests and code linters support the software developer. Specifically Vale allows text to be validated against style guides and custom spelling rules. A set of well regarded style guides are provided, but projects are free to add their own rules to reflect their specific needs. After this workshop you should be inspired and be able to easily add Vale to your current project. This tutorial walks through: 1. How to add Vale to an existing project and using pre-existing style guides 2. Setting up custom spelling rules and dictionaries 3. How to configure Vale for specific file formats and style guides 4. Adding or modifying style guide rules 5. Some of the pitfalls of using reading metrics. An example project will be provided for students to implement Vale. However feel free to bring your own project in Markdown, reStructuredText, or AsciiDoc. Before attending the workshop your should install the Vale binary on your machine (see https://vale.sh/docs/vale-cli/installation/) and a text editor. Vale works on Linux, macOS, Windows, and in a container image.