Fixed examples would be more useful, initially, than live ones

[pbiggar]

A user says:

In terms of documentation, I think it's really information first, a little bit of information hierarchy, and then maybe live examples after that. Stuff like how the version numbers are unformatted, there's no distinction between infix and prefix methods, there are some formatting bugs around the ::map2 functions, inconsistencies in sentence form, and stuff like that. How the type signatures refer to Blocks, but the docstrings refer to lambdas. || and ^ are at the end of the list, pretty far away from other boolean & arithmetic operators. Some of the docstrings are pedantically wrong, like modulus being documented as 15 % 6 = 3, where that should be a ==.

There's also some weakness around the type signatures themselves - for example, List::tail is documented as (List list) -> Option when I'd expect something like (List list) -> Option List, which would make it clear what value that option potentially contains.

So I think that level of consistency & housekeeping would help, but then examples would help a bit more - fixed examples would be more useful, initially, than live ones, because fixed examples demonstrate what sorts of values and situations are appropriate.

Hope this helps! Might be a bit more pedantic than your average user, but for us reference-doc reading folks, it's super important.

[tmcw]

👋 This was me, interested to see where this goes

[pbiggar]

This is a really useful list of concrete docs fixes we can do.

There's also some weakness around the type signatures themselves - for example, List::tail is documented as (List list) -> Option when I'd expect something like (List list) -> Option List, which would make it clear what value that option potentially contains.

I'm working on updating our types to allow this: the backend types are polymorphic now, when they didn't used to be, so adapting the frontend types to match them. Then we'll be able to display them better once the data is there.

In terms of documentation, I think it's really information first, a little bit of information hierarchy, and then maybe live examples after that. Stuff like how the version numbers are unformatted, there's no distinction between infix and prefix methods, there are some formatting bugs around the ::map2 functions, inconsistencies in sentence form, and stuff like that. How the type signatures refer to Blocks, but the docstrings refer to lambdas. || and ^ are at the end of the list, pretty far away from other boolean & arithmetic operators. Some of the docstrings are pedantically wrong, like modulus being documented as 15 % 6 = 3, where that should be a ==.

Now that dark is source available, if you wanted to take a stab at these fixes, we'd definitely merge them.