Our great sponsors
-
-
InfluxDB
Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.
-
-
-
hitchstory
Type-safe YAML integration tests. Tests that write your docs. Tests that rewrite themselves.
-
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
-
Every time I see a respectable project use a Code of Conduct I remind myself that, unfortunately, Caroline Ada won[1]
[1] https://github.com/opal/opal/issues/941
I present you Ayo.js, a long-dead Node.js fork with almost as many moderators as "core" members. I'm sure there are a variety of reasons why it bit the dust but I'll always view it as a lesson in priorities.
https://github.com/ayojs/ayo
As the dictator author/maintainer of a tiny library¹ (45 functions total), I can confirm the manual wouldn't be half as good without external contributions. And I daresay this manual is a major contributor to the usability of the whole project.
As a new user of libcurl, I was recently able to quickly implement FTP upload and adapt it to our specific use case thanks to their tutorials and API documentation. I was even made aware of the lack of thread safety in old versions thanks to that same documentation, so I could warn my team that we should update.
Documentation is bloody important. Almost as important as the code and the test suite themselves.
[1]: https://monocypher.org
Unit-tests are built into the language, as is comment-based documentation—put those two together and you get unit-tests as documentation examples built into the language; all it takes is to put a documentation comment (which can be blank) right before a `unittest` block after a declaration.
E.g. the examples for the D standard-library's `curry` function are just unit-tests: the docs: https://dlang.org/phobos/std_functional.html#quickindex.curr... the code: https://github.com/dlang/phobos/blob/42b8c65ccfd35c863f7cedf...
I took the same approach to "docs are tests and tests are docs" with integration testing when I created this library: https://github.com/hitchdev/hitchstory
I realized at some point that a test and a how-to guide can and should actually be the same thing - not just for doctests, but for every kind of test.
It's not only 2x quicker to combine writing a test with writing docs, the test part and the docs part reinforce each other:
* Tests are more easily understandable when you attach written context intended for human consumption.
* Docs are better if they come attached to a guarantee that they're valid, not out of date and not missing crucial details.
* TDD is better if how-to docs are created as a side effect.
It's just as true today, though. When the Rust mod team resigned en masse in 2021, it was announced by a programmer (the author of ripgrep) [0], and the conflict was with the core team (also programmers). A supermajority of their contributors to open source projects are programmers, so most famous meltdowns are going to be conflicts between programmers, not between programmers and the tiny minority of non-technical contributors.
I'm still waiting for anyone to give an example of an open source project meltdown that was triggered by non-technical contributors.
[0] https://github.com/rust-lang/team/pull/671
The ncurses/xterm maintainer also had quite a lot of friction with the developer of the kitty terminal emulator.
https://github.com/kovidgoyal/kitty/issues/879
> Examples in documentation can (for some doc frameworks & languages) be set up to run as tests, ensuring they stay current and actually work.
As an example, in Elm (as in many languages) your publicly exposed functions in a package (a.k.a. library) are required to have documentation comments. This often includes a simple example because, well, it's easy to grasp. The build tool elm-verify-examples runs all of these examples and verifies that the output is what you say it is. It pretty cleverly uses the inline comment delimiter as the start of an arrow so that the rendered code listing in the example is still syntactically correct.
https://github.com/stoeffel/elm-verify-examples
Just try Ansel. I saw this topic a while ago. https://news.ycombinator.com/item?id=38390914
I am only familiar with his YouTube, and then this topic. https://github.com/aurelienpierreeng/ansel Here are his examples.
It seems 1:1 compatible when I switched.