I’m a professional software writer specialized in Web technologies and engaged in indie application development. I consider myself to be a man of faith. I pursue honesty, integrity, and compassion.
I think the ideal would be a combination of JS style docs, where most of the documentation for a lot of libraries is in the README with a few examples, and the Haskell style, where types are often all you're given.
I found that as I got better at reading type signatures, I much much much preferred Elm's package repository and documentation to what can normally be found on NPM, but that was totally because I learned to read the type signatures (which took practice).
As much as I love having type signatures in the documentation, the presence of helpful types in Elm's package documentation can make it more difficult for package authors to remember to write out good examples. And examples are definitely needed in many cases to make sense of how the libraries are intended to be used. That's a way in which the community can improve.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I think the ideal would be a combination of JS style docs, where most of the documentation for a lot of libraries is in the README with a few examples, and the Haskell style, where types are often all you're given.
I found that as I got better at reading type signatures, I much much much preferred Elm's package repository and documentation to what can normally be found on NPM, but that was totally because I learned to read the type signatures (which took practice).
As much as I love having type signatures in the documentation, the presence of helpful types in Elm's package documentation can make it more difficult for package authors to remember to write out good examples. And examples are definitely needed in many cases to make sense of how the libraries are intended to be used. That's a way in which the community can improve.