Should programming language docs come with exercises for the reader to test their understanding?
This feels like a great way to help people learn, and you could even measure docs by pass rate.
I've seen online books occasionally use this format, but never official resources.
miniblog.
Related Posts
34
I'm trying to decide what program I should show on the home page of my PL.
Hello World is too simple to show much syntax. Fibonacci is OK but the reader may not know what print(fib(10)) should show.
Maybe print(greet("World")) is better? It gives you a function definition at least.
6
Trying the nix CLI today, and I'm seriously impressed with the formatting of its --help output.
Indented warnings, italics, bullets, even adding a left border to code snippets! It's a nice reminder to take full advantage of terminal features to help the reader.
47
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?