4 ms·

Seconded on examples, but example code needs to be integrated into software testing for projects that are frequently updated. Broken examples are arguably worse

Seconded on examples, but example code needs to be integrated into software testing for projects that are frequently updated. Broken examples are arguably worse than none. Even less arguable is when examples that worked are broken by an update and remain unchanged--they'll work for people on outdated versions but break when they upgrade, and also break for new users, and nothing will sufficiently explain why. Please add your documentation examples to your testing pipeline (or write tests clearly enough that they can be good examples, and just use those).

ShamelessC 7y ago
> Please add your documentation examples to your testing pipeline (or write tests clearly enough that they can be good examples, and just use those). This seems like a pretty good practice to me. Are there any good testing libraries for keeping your documentation examples tested and up to date?
- ithkuil 7y ago
  A language specific answer: The testing package of the Go standard library has a built-in support for examples. They are executed as part of the tests, but are rendered by the documentation generator as examples. This obviously only solves the problem of library writes that want to expose examples of library usage (and ensure they don't get stale)
  - adamhepner 7y ago
    This is such an amazing feature. I wish it got picked up by other major languages and became a standard practice.
- frobozz 7y ago
  Python has doctest, which can be run on its own or integrated with documentation generators (e.g. Sphinx) and testing libraries (e.g. pytest)
pytester 7y ago
I actually wrote a testing framework with the idea that specification, tests and documentation should all be the derived from the same source: https://hitchdev.com/hitchstory/using/alpha/generate-documentation/ https://hitchdev.com/hitchstory/using/alpha/generate-documen... The same YAML files that are used to regression test the software are used to generate markdown docs for the website.

ShamelessC 7y ago

> Please add your documentation examples to your testing pipeline (or write tests clearly enough that they can be good examples, and just use those). This seems like a pretty good practice to me. Are there any good testing libraries for keeping your documentation examples tested and up to date?

ithkuil 7y ago
A language specific answer: The testing package of the Go standard library has a built-in support for examples. They are executed as part of the tests, but are rendered by the documentation generator as examples. This obviously only solves the problem of library writes that want to expose examples of library usage (and ensure they don't get stale)
- adamhepner 7y ago
  This is such an amazing feature. I wish it got picked up by other major languages and became a standard practice.
frobozz 7y ago
Python has doctest, which can be run on its own or integrated with documentation generators (e.g. Sphinx) and testing libraries (e.g. pytest)

pytester 7y ago

I actually wrote a testing framework with the idea that specification, tests and documentation should all be the derived from the same source: https://hitchdev.com/hitchstory/using/alpha/generate-documentation/ https://hitchdev.com/hitchstory/using/alpha/generate-documen... The same YAML files that are used to regression test the software are used to generate markdown docs for the website.