In reply to @fricklerhandwerk:matrix.org

My opinion on this somewhat technically unqualified because I haven’t done concrete work on it, but I see a few theoretical advantages to have pairs of code blocks for input/output:

• No fancy parsing needed, can be hooked into markdown processors. On nix.dev we have highlighting of expression/value pairs which demonstrate this.
• Easier to type, obvious how to copy paste
• No implicit state possible or required. State bad.

Generally documentation (and everything, really) should be low-tech so it’s easy to contribute to and understand how it works. That is, it shouldn’t do anything clever, because it will be hard to change for most people if it does, if only because it requires time to figure out. And time is a very scarce resource.

Based on your input: https://github.com/NixOS/nix.dev/issues/864

I am not sure if this qualifies as low-tech. Maybe it does because all it uses is a CLI tool. With modern tools, it is easy to make a heavily automatically documented CLI tool (e.g. if using Rust: can use bpaf/clap both convert doc strings into CLI help strings).

However, low-tech ought to be measured against cost-of-manual-work? In this particular case: cost of copying+pasting, verifying output expression against expectation, validating that examples remain valid across Nix updates.

In reply to @fricklerhandwerk:matrix.org

My opinion on this somewhat technically unqualified because I haven’t done concrete work on it, but I see a few theoretical advantages to have pairs of code blocks for input/output:

• No fancy parsing needed, can be hooked into markdown processors. On nix.dev we have highlighting of expression/value pairs which demonstrate this.
• Easier to type, obvious how to copy paste
• No implicit state possible or required. State bad.

Generally documentation (and everything, really) should be low-tech so it’s easy to contribute to and understand how it works. That is, it shouldn’t do anything clever, because it will be hard to change for most people if it does, if only because it requires time to figure out. And time is a very scarce resource.

Based on your input: https://github.com/NixOS/nix.dev/issues/864

I am not sure if this qualifies as low-tech. Maybe it does because all it uses is a CLI tool. With modern tools, it is easy to make a heavily automatically documented CLI tool (e.g. if using Rust: can use bpaf/clap both convert doc strings into CLI help strings).

However, low-tech ought to be measured against cost-of-manual-work? In this particular case: cost of copying+pasting, verifying output expression against expectation, validating that examples remain valid across Nix updates.

(Regardless: not a "must-do". Only a "could-do". Happy to execute on a draft version, if time can be made for its review, with full understanding that it will likely not be accepted.)

Based on your input: https://github.com/NixOS/nix.dev/issues/864

I am not sure if this qualifies as low-tech. Maybe it does because all it uses is a CLI tool. With modern tools, it is easy to make a heavily automatically documented CLI tool (e.g. if using Rust: can use bpaf/clap both convert doc strings into CLI help strings).

However, low-tech ought to be measured against cost-of-manual-work? In this particular case: cost of copying+pasting, verifying output expression against expectation, validating that examples remain valid across Nix updates.

(Regardless: not a "must-do". Only a "could-do". Happy to execute on a draft version, if time can be made for its review, with full understanding that it will likely not be accepted. Will not create a draft version if it only adds to review burden.)

Based on your input: https://github.com/NixOS/nix.dev/issues/864

I am not sure if this qualifies as low-tech. Maybe it does because all it uses is a CLI tool. With modern tools, it is easy to make a heavily automatically documented CLI tool (e.g. if using Rust: can use bpaf/clap both convert doc strings into CLI help strings). However, it is still a tool, and the use of a tool necessarily moves us farther away from low-tech.

However, low-tech ought to be measured against cost-of-manual-work? In this particular case: cost of copying+pasting, verifying output expression against expectation, validating that examples remain valid across Nix updates.

(Regardless: not a "must-do". Only a "could-do". Happy to execute on a draft version, if time can be made for its review, with full understanding that it will likely not be accepted. Will not create a draft version if it only adds to review burden.)

In reply to @mightyiam:matrix.org
bzm3r: the doctester is coming along

In reply to @mightyiam:matrix.org
bzm3r: the doctester is coming along

Repl example example:

```nix-repl
nix-shnepl> nope
dope
```

Expression example example:

```nix
null
```

If it evaluates into null then it's good. If it evaluates into anything else it's bad. If it fails to evaluate, it's bad. The idea is that the author will use Nix assertions to prove their points in the example.

In reply to @mightyiam:matrix.org
Sorry, there's no documentation. There are tests for the repl examples and there are tests for the WIP expression examples.
https://github.com/mobusoperandi/eelco/tree/0eb9042220befe188aa4399ffc6615579cebdd5f/crates/eelco/tests