The docs model for R packages is really interesting. Every package has docs as a PDF file, and the package server supports 'vignettes' (standalone tutorials) as a first class artifact!
E.g.
miniblog.
Related Posts
When a tool supports both regular expressions and literal strings, which should be the default?
If you default to regex, users can match more strings than they realise (e.g. `foo.txt`) or less (e.g. `foo(bar)`).
I typically see regex as the default, but I prefer the opposite.
I'm trying to decide the best voice for PL documentation.
Passive: "`let` can be used with destructuring."
Reader focused: "You can use `let` with destructuring."
Describing the PL: "FooLang supports destructuring with `let`."
Anyone have opinions or best practices?
After seeing yet another YAML dialect for controlling systems, I think we need a hierarchy of YAML dialect expressiveness.
(1) Has its own variable binding system.
(2) Supports if statements.
(3) Supports loops.
(4) Supports function definition.
2 seems to be the most common, but I've seen all of 1-3. Does level 4 exist in the wild yet?