[petcat]

Out-of-band docs have always been a constant source of frustration and discrepancies. It's really difficult to keep readme.com docs updated with actual code releases because there's no hard constraint preventing one from updating without the other. It just relies on "convention".

[thangalin]

> difficult to keep [...] docs updated with actual code

I used my software and R Markdown documents to help address such problems. In the source code, you have:

    // DOC SNIPPET BEGAN: example_api_usage
    /**
     */
    function amazing_function( char life, long universe, string everything ) {
    } 
    // DOC SNIPPET ENDED

In the R Markdown you write an R function to parse all snippets, then refer to snippets by name. If the snippet can't be found, building the documentation fails, and noisily breaks a CI/CD pipeline.

What's nice is that you can then use this to parse C++ definitions into Markdown tables to render nicely formatted content.

The general idea is that you can have "living" documentation reference source code and break on mismatch. Whether you use knitr/pandoc or python or KeenWrite/R Markdown[1] is an implementation detail.

[1]: https://keenwrite.com/

[moritz]

In the Elixir ecosystem (where documentation is considered a "first-class citizen" in the language), you can run code examples as part of your test suite in a similar fashion ("doctest"): https://elixir-recipes.github.io/testing/doctests/

[thangalin]

> documentation is considered a "first-class citizen"

How exquisitely Knuthian!