Less versatility at the beginning of `README.md`?

[piotr-yuxuan]

I'm really a great fan of this library, and there is this feeling that it is becoming kind of one of Clojure's missing pieces. I think the library core is extremely well-designed, and that allows very unopinionated, versatile usage like:

• Vector, map, and lite syntax;
• Function schema via var metadata, separate declaration, and plumatic-style;
• Anything else I missed?

However, I don't know what would make the adoption / learning curve easier: perhaps it's great to show all the power from line 0 in the README.md, or might it be better to explain the core functionality with only one advised style for syntax and function schema, and elaborate later or in separate docs?

[esuomi]

First off, writing good documentation is possibly the hardest problem in software development, so even with nothing changing, I do have give a 👏 for the current README.

---

I think I agree, Malli's README has grown into a massive beast as more features and functionality has amassed, and it has to be daunting for people new to Malli to figure out how to use the library and what can be done in general.

A few thoughts that I think could be done to help with this:

Distill the README to basic usage, move advanced topics to separate files

In my opinion the main README should only serve the basic usage and show a teaser of each advanced feature not directly related to core functionality with a link to comprehensive feature documentation. It might be hard to choose what's "core" and what's "advanced" beyond defining schemas and their use in validation, and I know there's a separate school of thought on whether README should be one long document or split into multiple, but I'd rather see per-feature documentation pieces under docs/*.md for those of us who want to deeply understand transformations, spell checking, seqexps, value parser and so on and so forth and keep the README as a baseline understanding, a sort of introductory class to the library itself.

Section ordering could be improved

Some of the difficulty is definitely caused by section ordering, I don't think at this point there isn't that much benefit in haing a screenshot of IDE and a page-long read about motivation before actual usage section, currenty labeled under main headline "The library" and onwards. As per documentation quadrants, the main README should be all about How-To guides first, followed by Reference while feature specific Tutorials and Explanations should follow the more of a quick start approach. In my opionion well written How-To and Reference should tease people into Tutorials and Explanations :)

Comparing to Plumatic Schema's documentation and what I just wrote there, one section I really miss is this: https://github.com/plumatic/schema#other-schema-types the greatness of this Reference is that it's one top-to-bottom run-through of all supported features and could be used as a cheatsheet on its own. Malli's README does have near the bottom listings of the contents of various built-in schemas, but no usage examples, and I'm not sure if even the core schemas are all documented comprehensively.

[piotr-yuxuan]

I for one would also give kudos to the current README! Sorry if it wasn't clear in my first message.

Regarding documentation quadrant, I recently found this very similar page https://diataxis.fr/