On Documenting the actual limitations of Mint and improving developer experience

[frnco]

I've been using Mint for a while now, have used Elm for a few small projects before, and I have even used Crystal in a substantial number of small personal projects. I've learned that Mint unfortunately shares some of Elm's problems, most notably the shallowness of the documentation and scarcity of examples, but also some seemingly arbitrary limitations of the APIs, such as having to keep converting to and from strings when binding data to an input even though it's type="number", and updating a value that is nested in a state variable, as an example, I can't find a reasonably concise and straightforward way of updating the names on something like state people : Array(Person) = [{firstName="John",lastName="Doe",age=38},{firstName="Jane",lastName="Doe",age=36}], much less the ages since those would add a lot of boilerplate just for converting between Number and String, and simply using Arrays/Sets/Maps already means I have to check for Maybe"s everywhere (Even if I get the Index of something in the Array/Set and later use it to update the array, which I'd expect to be fail-safe, requires such Maybe` checks).

Now, from my experience Elm is a lot more verbose and requires an unreasonable amount of boilerplate, so I feel Mint is already quite better, but a lot of blind experimentation is still necessary to build pretty much anything, the documentation is just way too basic, at least in my opinion, and here it's worth to point out that I've been using Arch Linux for almost a decade and have some experience with Gentoo, and I believe the Arch and Gentoo Wikis are widely known for how detailed, complete and well-written they are, couple that with how Arch tends to push users towards learning and deciding by themselves how to do things and it's pretty much a given that I have quite a bit of experience going through documentation to figure stuff out.

Now, Mint's documentation is not wrong, but it's definitely lacking. The API Section lacks not only examples but also depth/detail, to mention a few:

1. What's the difference between Storage.Local and Storage.Session? How should I expect stored data to behave? or;
2. In Json.stringify how should I proceed when I want to either indent or minify or do whatever with the resulting string...?

And this API section doesn't touch on Syntax and language stuff, which takes us to my second point: The Learn section.

The Learn section is actually quite good, it gives a reasonably good overview of the language itself, but one of the reasons for that is its simplicity, and that means quite a bit of stuff is actually left out. I think that should be adressed by adding a new section with advance stuff so as to avoid over-complicating the Learn section, but even then there are some points that could and should be made clearer in the Learn section itself, to mention just a few that have bothered me in the past:

1. A lack of examples on the "Handling Events" bit, which doesn't include an example for the onChange handler which is very basic;
2. Lack of examples under both Referencer -> Records and Control Expressions -> Next sections, leaving out things like uploading arrays or nested fields and only giving one example on the shorthand to update a single field on a record, the example being { user | name = "Stuart" } (Which obviously doesn't give any information on dealing with either arrays or nested fields).
3. The Type System and Javascript Interop sections are so poorly documented I was actually shocked by this example: https://sandbox.mint-lang.com/sandboxes/Tf54Ptl0zxTCnw

Which takes me to my last point, the Try/Sandbox area of the site. As it stands, it's a very short list containing only the 20 most recent sandboxes created (Maybe updated?) by anyone, which causes it to mostly be a collection of useless examples that do not work. It should either present a selected list of knowingly useful sandboxes, which should be easy to do since it'd require picking just 20 sandboxes, or it should have some way to browser/search/whatever. As it stands it's pretty much impossible to find anything useful over there.

Now since my intention is to help improving this and not only complaining, I do have some ideas and I hope we can collectively find solutions to those problems. First of all, I believe something like a wiki, which allows people to contribute with more details, examples etc., could be a nice way to fix most of those issues. On the Sandbox bit, I'd suggest either a search box or a simple pagination, whichever is easier to implement. And last but not least, the addition of a page on the "Learn" section about ways to contribute to the documentation specifically. As familiar as I am with Crystal I'm no language designer, so it's a really big hurdle to get involved with the Github issues, which I did check out to see if there was anything I could help with.

I believe Mint is clearly superior to every single one of its alternatives when talking about Front-end design, probably even when considering UI design as a whole, and I think in the near future the adoption of Mint, Elm or something similar will rise dramatically, but the current state of documentation for Mint is definitely one of the biggest obstacles for new developers, and not everyone is as eager as I am to try out shiny new things, or as experienced as I am so as to have enough experience/knowledge to fill in the gaps of the documentation.

[gdotdesign]

Thanks for writing this 👍 🙏

I'm on holiday at the moment, when I get back I'll address the points you raised in more detail, but for now I just point here the places where the documentation can be contributed to:

• API Section - it's generated from comments in the core library here: https://github.com/mint-lang/mint/tree/master/core/source
• Learn Section - the website is a Ruby on Rails application where every page is in a separate file: https://github.com/mint-lang/mint-website-rails/tree/master/app/views/guides
• Sandbox - the backend of the sandbox is the same as the website above, the front-end is a Mint application which lives here: https://github.com/mint-lang/mint-sandbox
• Tutorial - I've started a tutorial site like what Svelte has, but it's very incomplete: https://tutorial.mint-lang.com/introduction/basics https://github.com/mint-lang/mint-tutorial

So if you would like to contribute, you can do that in any of those, if you need specific guidance we can chat on Discord, Gitter or Telegram.

To clarify why the documentation is so poor: my issue is that I don't see where the documentation can be improved because I know everything, and it's not evident for me 😞

[frnco]

To clarify why the documentation is so poor: my issue is that I don't see where the documentation can be improved because I know everything, and it's not evident for me disappointed

That totally makes sense. I've been using Mint more and more and as I learn more it becomes easier and easier to figure out where in the documentation I should look for answers. As a suggestion of some specific pain points I've encountered, some of which I still haven't figured out, at least not enough to make me comfortable with my solutions, are:

1. Providers, more specifically the need to use the Subscription fields when writing the use code and implementation details for things like the fields in the Provider.Intersection.Subscription, and probably many others, which is so poorly documented that I actually gave up on figuring that out and just used some inline Javascript instead.
2. Events, my most recent encounter with this was making a Search Box, I wanted to have the search triggered by either the Enter key or clicking a button, besides having to store the searchbox value in a temporary store I went through checking onInput, onSubmit, onChange (Which is still in use to update the store value and keep it synced to the actual input element) and finally got to onKeyUp which was able to detect the Enter key.
3. Encoding/Decoding Json and Objects to and from Javascript, especially Enums (Though Dates/Times have also troubled me in the past), and even more especially when they're on a deeper layer in the data structure. I just found an issue relating to destructuring Enums and I'm absolutely thrilled about figuring this stuff out.
4. Routing, or more specifically how to properly structure my code to properly use Routes. In the Docs there is an example which uses Application.setPage but I haven't found any examples of how that could be written. In my case I quickly noticed I wouldn't be able to call a component from the routes and created a store Application to work stuff out, and it worked quite ok, but it's still not perfect, plus I'm totally confused as to what is or isn't URL-Encoded/Decoded when creating links and reading from the routes, so it'd be nice to have some info about that in the Docs.
5. External files, most notable here is reading JSON files and using the data, I don't care whether it happens at compile or execution time, my best example of this was a small website I made for my dad with some audios and photos of my grandparents, both deceased. I had 87 pictures to include, pretty straightforward, put all the filenames in an array and use a for to render them as a gallery or whatever, but Mint being Mint that data had to be in the code, I couldn't import a txt or json file with the names, and for a static site, especially if you're planning to make it something like a hybrid app or maybe github pages or whatever, being able to include data from Json at compile time (Since you may have neither a server nor access to the filesystem) would be pretty useful.
6. This is actually mostly an extension to 5, and probably belongs in the roadmap, but on the off-chance that I've missed something I'll mention this, which in my case relates to doing Internationalization on a small side-project. This probably should be done by a macro system, but in my case I just wrote a simple ruby script that outputs a I18n.mint file, it reads a folder with multiple yaml files, each for one language with the strings in that language, and outputs the I18n.mint file with the language codes as an enum, a record with all the available fields, and a store I18n that has a state which is a language code and retrieves the string according to that state. I did the same ruby-script approach to read the names of all icons from https://feathericons.com/ and produce a mint file with an enum containing all the possible icon names and a component that takes an Icon name (Checked against the enum) and renders the Html for the corresponding icon. As I said, this should probably be dealt with using Macros but in case there's any way to dynamically generate Enums or some other way I've missed, it would be nice to have something about it in the Docs.

There are many other issues that have bothered me, like dealing with Maybe, Result and, most notably, items in a set. I'm completely unsatisfied with how I've been dealing with those, usually there are way more Maybe.just(something) in my code than I'd like, and keeping track of data in situations where I can dynamically add items, then have all of them each tied to inputs or whatever, then when updating one having to check the list for the item, to finally update it, and after all that also having to update the whole list is quite a pain, but I'm not even sure if the language has better ways to deal with those kinds of situations so I won't go deeper on those, at least not until I understand them well enough to have something meaningful to contribute.

I hope this helps with at least figuring out which parts of the documentation need more attention. Hopefully I'll soon be able to contribute to the docs with some PRs, but for now I'm still working on getting a deeper understanding of the language, its limitations, hows and whys.