Tip of the Week: Linting Documentation as Code
Tip of the Week: Linting Documentation as Code
Each week we seek to provide a software tip of the week geared towards helping you achieve your software goals. Views expressed in the content belong to the content creators and not the organization, its affiliates, or employees. If you have any software questions or suggestions for an upcoming tip of the week, please don’t hesitate to reach out to #software-engineering on Slack or email DBMISoftwareEngineering at olucdenver.onmicrosoft.com
Software documentation is sometimes treated as a less important or secondary aspect of software development. Treating documentation as code allows developers to version control the shared understanding and knowledge surrounding a project. Leveraging this paradigm also enables the use of tools and patterns which have been used to strengthen code maintenance. This article covers one such pattern: linting, or static analysis, for documentation treated like code.
TLDR (too long, didn’t read); There are many linting tools available which enable quick revision of your documentation. Try using codespell for spelling corrections, mdformat for markdown file formatting corrections, and vale for more complex editorial style or natural language assessment within your documentation.
Spelling Checks
<!--- readme.md --->
## Example Readme
Thsi project is a wokr in progess.
Code will be updated by the team very often.
(CU Anschutz)[https://www.cuanschutz.edu/]
Example readme.md with incorrectly spelled words
% codespell readme.md
readme.md:4: Thsi ==> This
readme.md:4: wokr ==> work
readme.md:4: progess ==> progress
Example showing codespell detection of mispelled words
Spelling checks may be used to automatically detect incorrect spellings of words within your documentation (and code!). Codespell is one library which can lint your word spelling. Codespell may be used through the command-line and also through a pre-commit hook.
Markdown Format Linting
<!--- readme.md --->
## Example Readme
This project is a work in progress.
Code will be updated by the team very often.
(CU Anschutz)[https://www.cuanschutz.edu/]
Example readme.md with markdown issues
% markdownlint readme.md
readme.md:2 MD041/first-line-heading/first-line-h1
First line in a file should be a top-level heading
[Context: "## Example Readme"]
readme.md:6:5 MD011/no-reversed-links Reversed link
syntax [(link)[https://www.cuanschutz.edu/]]
Example showing markdownlint detection of issues
The format of your documentation files may also be linted for common issues. This may catch things which are otherwise hard to see when editing content. It may also improve the overall web accessibility of your content, for example, through proper HTML header order and image alternate text. Markdownlint is one library which can be used to find issues within markdown files.
Additional and similar resources to explore in this area:
- restructuredtext-lint - for linting RST files
- mdformat - an additional markdown linter
Editorial Style and Grammar
<!--- readme.md --->
# Example Readme
This project is a work in progress.
Code will be updated by the team very often.
[CU Anschutz](https://www.cuanschutz.edu/)
Example readme.md with questionable editorial style
% vale readme-example.md
readme-example.md
2:12 error Did you really mean 'Readme'? Vale.Spelling
5:11 warning 'be updated' may be passive write-good.Passive
voice. Use active voice if you
can.
5:34 warning 'very' is a weasel word! write-good.Weasel
Example showing vale warnings and errors
Maintaining consistent editorial style and grammar may also be a focus within your documentation. These issues are sometimes more difficult to detect and more opinionated in nature. In some cases, organizations publish guides on this topic (see Microsoft Writing Style Guide, or Google Developer Documenation Style Guide). Some of the complexity of writing style may be linted through tools like Vale. Using common configurations through Vale can unify how language is used within your documentation by linting for common style and grammar.
Additional and similar resources to explore in this area:
- textlint - similar to Vale with a modular approach
Resources
Please see the following the resources on this topic.
- codespell - a code and documentation spell checker.
- markdownlint - markdown linter.
- mdformat - another markdown linter.
- restructuredtext-lint - RST file format linter.
- vale - an editorial style linter.
- textlint - another editorial style linter with greater modularity.