One of the main bullet points on the page is automated tests.
How do you write automated tests for documentation? Somehow require that blocks of code have documentation linked to them?
How do you write automated tests for documentation? Somehow require that blocks of code have documentation linked to them?
It could be tests to ensure documentation "builds" into all of the desired formats (e.g. web, pdf, ebooks, etc.) correctly.
Some programming languages have the idea of "documentation tests". In Rust, tests that are part of the documentation will run as part of the documentation build:
https://doc.rust-lang.org/rustdoc/write-documentation/docume...
I admit that, while I write instructions for how to test specific functionality in gherkin, our company would not countenance publishing a non-narrative description of the system's behavior to our client's employees.
[0] https://www.manning.com/books/writing-great-specifications
Given a work order xx
and xx isExpedite
When an operator prints the jobcard
Then expect a label in the footer that says Expedite
- Making sure example snippets still compile
- Checking if links are dead
- Check for standardized/proper formatting
Basically anything you'd want to enforce manually, try to enforce with CI.
See https://docs.python.org/3/library/doctest.html#module-doctes... as an example.
Short version: have tests that use introspection (listing functions and classes in a module, iterating over JSON API endpoints in the codebase etc) and then run regular expressions against your documentation searching for relevant headings or other pre-determined structures.
But I too would be interested to hear other people's insights who subscribe to this Docs as Code model.
The Symfony (PHP) framework now does this. Code and config examples in the docs have automated regression tests.
Here are some other Good Ideas in a blog post I stumbled upon the other week: https://azdavis.net/posts/test-repo/