Fork me on GitHub
Martynas M12:04:59

Hey. There is a guy that asks for more transparency on what the library supports. I'm not too sure how to answer his question. This probably means that he'd expect to either be dismissed and pointed into README once again or then the README should be updated.


I took a crack at answering.


There is a theory of documentation, that I first saw promoted by Jacob Kaplan-Moss (highly influential in Django documentation and later Heroku Developer Center), that divides documentation into 4 kinds: tutorials, how-to guides, reference and explanation. In general, when I see people struggling with documentation, it is often because the author of the document in question and the reader are in two different quadrants - neither is wrong, but they're missing each other instead of mind-melding. @invertisment_clojuria - having skimmed the linked issues, I think the same mismatching of expectations is happening. Malli does have some tutorial-like and explanation-like content in the README, and one can explore the codebase and tests to gather more reference-like content. gives examples one may consider how-to guides for modeling common schemas. But I think it is a fair assessment that all these things are scattered and not easy to find, especially for a newcomer to the library. Aside from Jacob Kaplan-Moss talks and writing you can find online, I found a good write up of the problems with structuring documentation here: I think moving forward, malli would benefit by taking some pointers for how to organize different kinds of documentation and information for the community. It's not a question of what should be in the README, tests, etc., but more of a question of how to organize this information that a reader coming to the project with different mindset and expectations can find the information that is most relevant for them at the time.

👀 1
❤️ 3

Hi, did a bit of a hit&run yesterday with this, but wanted to comment 🙂 I totally agree with this! Documentation, in general, is both incredibly hard and incredibly valuable, and I do use that divio link every time I talk about software documentation to anyone as reference - I don’t claim it to be perfect, but it is definitely good enough. For me, malli’s documentation currently has a discoverability issue. Over the past few years malli has gained a daunting amount of features, but there’s no clear path to learning each feature, and the readme’s examples aren’t comprehensive - this latter is especially kinda amazing considering the readme is probably the longest I’ve ever seen in a Clojure project, especially when considering the amount of examples. To generalize what I want from documentation is three things: 1. How do I use this. This is always the most critical one, and a sort of blindfold approach - if there isn’t a direct “do x to get y, do z after doing y to get z” kind of How-To guide, I’ll probably never learn about That One Awesome Feature. This is sort of related to the eternal discussion of if left fold is enough or should we also have map and reduce, or is filter enough or do we need keep and remove as well. 2. What is the internal logic. I don’t mean algorithms or stuff like that, but why are things organized in the way they are and what are the architectural decisions. “We like interceptors over middleware” sounds nice, but that assumes I know what interceptors and middleware are. Another would be naming schemes used to name functions, especially prefixes and suffixes used, stuff like that, or something thankfully not that common in Clojure land, but do you return raw values, lazy seqs, promises, do you assume your library is being used from the outside? 3. All I need is the documentation. If I need to read the source to understand software behavior, the documentation sucks. I’ve been told especially about this that I am Wrong™, but I don’t have time nor interest for that debate - this is my approach 🙂 From technical point of view IMO malli should add one of those libraries which can evaluate code snippets in README just to make sure the snippets stay current and working. Sort of related but inevitable is also the fact that malli’s build is now build+deps based, which is like all over again, but ehhhh pointing back to my previous points, if I need to worry about how malli is built, I’m already too deep… 🙂

❤️ 1

Thanks for the long and insightful comment @U8SFC8HLP :) It's going to be a slow start, but I'm willing to try to help out with this kind of documentation in the coming weeks. So the core team can focus on delivering more awesome features. ;) I see Tommi is vacationing atm, but I wonder if other malli contributors or users have more insights on what they'd like to see. I'll start taking some notes.


@UK0810AQ2 , you had a tutorial almost done? PR would be most welcome. Also, @U05476190 & all, all documentation improvements are most welcome, /docs being a good place for them.

👍 1