Reference docs should be made comprehensive

[jiggneshhgohel]

Hello,

I real feel that the Reference lacks some important details about the language's concepts. For e.g. yesterday I was exploring https://github.com/mint-lang/mint-realworld and while going through

https://github.com/mint-lang/mint-realworld/blob/5d7da20a587c365aed146e6420e3c083a9cf2c11/source/Pages/SignUp.mint

I was trying to understand how on Sign Up if any errors are encountered will be rendered by following line

https://github.com/mint-lang/mint-realworld/blob/5d7da20a587c365aed146e6420e3c083a9cf2c11/source/Pages/SignUp.mint#L33

So I checked that the component is defined as an async component (L1). So I checked the docs at https://mint-lang.com/reference/components/async-components but still couldn't make it because the docs illustrate following example

async component Greeter {
  fun render : Html {
    <div>
      "Hello World! I'm loaded asynchronously!"
    </div>
  }
}

component Main {
  state shown : Bool = false

  fun render : Html {
    <div>
      <button onclick={() { next { shown: true } }}>
        "Show Greeting!"
      </button>

      if shown {
        <Greeter/>
      }
    </div>
  }
}

That shows that Greeter component will render if shown state will be found true. That state is updated on click of "Show Greeting!" btn which is part of Main component. So to make the Greeter component show up Main component will need to re-render after the btn is clicked so that the if shown can evaluate to true and thus render Greeter component.

But the Pages.SignUp component in mint-realworld doesn't employ any such conditional approach to render following part:

<GlobalErrors errors={Api.errorsOf("request", status)}/>

So I was exploring here and there on Website Home, Tutorial and Reference and while doing that I found following:

• Ref: https://mint-lang.com/#stores-state

Stores can be connected to components to be re-rendered when data changes

• Ref: https://mint-lang.com/tutorial/language/stores

Any component referencing a store (like above) is re-rendered when data in it changes.

With that information when I again checked Pages.SignUp component in it I found Forms.SignUp connected. So checking
Forms.SignUp store at https://github.com/mint-lang/mint-realworld/blob/5d7da20a587c365aed146e6420e3c083a9cf2c11/source/Forms/SignUp.mint I could connect the missing links i.e. when Forms.SignUp store updates it's state status, then the components in which it is connected, which in present discussion is Pages.SignUp, then that component will re-run its render function and thus the GlobalErrors component should get a chance to render.

So my point is that the details are there but they are scattered in Tutorial or Reference or the Website's main page. I think Reference should be comprehensive. Tutorial is for getting started. But when one needs to dive deep s/he would ultimately prefer to check the Reference and API

---

One more example: In a discussion I opened #791 (comment) @gdotdesign shared about the shadowing technique for let assigments. But checking the Reference I couldn't find any dedicated section for let. If we follow the Reference in sequence then the first time you come across let is in https://mint-lang.com/reference/array but without any mention about what is its purpose. Then in https://mint-lang.com/reference/state-management an important piece is shared that let assignment cannot be changed.

Assignments are a critical part of the logic and let being the primary means I think it needs its own section explaining its usage and behavior. Ofcourse in https://mint-lang.com/reference/blocks some important information is available, but on the behavior that let's assignment cannot be changed, still if there is need to change, then whether it is possible or not, if possible how to do that etc should be explained. For e.g. in the referenced discussion my need was to push items to an Array and get hold of that updated Array so that it can be again operated on by further logic.

That said neither https://mint-lang.com/tutorial/language/arrays nor https://mint-lang.com/reference/array doesn't demonstrate Array modifications. I believe modifying Arrays (actually transforming Arrays in Functional Programming terminology like @gdotdesign shared in #791 (comment)) is an important part while building logic on them and thus the docs should illustrate that as well.

Hoping that this feedback for documentation will be taken on a positive note and accordingly consideration will be given to improve the documentation esp keeping in mind the developers, like me,

• who would be novices to functional programming paradigm
• who might not have worked with React domain
• who are not expert with advanced form of Javascript programming techniques like Promises, Typescript, NodeJS, Bundlers etc.

Thanks.

[gdotdesign]

Thank you for the lengthy post 🙏

I'm always trying to add more documentation, but it's hard from my perspective, since I don't run into issues like you do (meaning novice people) so I can't know what the shortcomings of the reference are.

I do believe that the path forward is that when people run into issues and have solutions, they contribute that back to the documentation. In this case, it would be you who creates a PR with the additions/changes. This (discussions) is a good platform too to express these issues, but it's not where people search in the first place. For more mature languages, the other platforms (Stack Overflow for example) have a lot of documentation on how to do things which might not be in the official documentation, unfortunately Mint is just not there yet.

So in short, I do know that there are missing things in the documentation, but I don't know what they are 🙂 and I hope people will contribute in the long run.

---

I'll update the documentation of the specific issues you mentioned or if you are willing a PR would be the best.

[jiggneshhgohel]

@gdotdesign

I'm always trying to add more documentation, but it's hard from my perspective, since I don't run into issues like you do (meaning novice people) so I can't know what the shortcomings of the reference are.

I can absolutely understand your perspective. It is hard to look at things from a different perspective esp when you are daily working on developing the language as well writing real-time applications with it. I believe to address such limitations only peer-reviews and pair-programming like concepts came into being in software development.

I do believe that the path forward is that when people run into issues and have solutions, they contribute that back to the documentation. In this case, it would be you who creates a PR with the additions/changes. This (discussions) is a good platform too to express these issues, but it's not where people search in the first place. For more mature languages, the other platforms (Stack Overflow for example) have a lot of documentation on how to do things which might not be in the official documentation, unfortunately Mint is just not there yet.

I agree mostly but I have a different perspective on consulting Stackoverflow like platforms. Usually the approach, esp of novices, is to search on Google for the problem they are facing with a language/framework/anything related and for almost anything Stackoverflow results should be found at the top in the search results so they would simply navigate to them.

But experienced developers would first consult the official documentation for the API they want to work with or for finding any API related to their need at hand and so they would first go to official documentation and then if not satisfied with docs, they would decide to check out Stackoverflow. For e.g. I have years of experience working with Ruby and Rails. So for any need with their features or syntax I would first consult their official docs and if not finding what is being sought I would decide to consult Stackoverflow.

So in short, I do know that there are missing things in the documentation, but I don't know what they are 🙂 and I hope people will contribute in the long run.

Agreed and that's why people who find Mint to have a potential spare time to explore it, experiment with it, submit feedback, ask questions etc through Discussions. After all it becomes a moralistic duty of such people who are using someone's work for free to help in any way possible in improvising that work. Sincere consumers of any open-source work appreciate the hard-work the voluntary contributors are putting forward to make the work production-ready and I personally find Mint to be a potential candidate in open-source community to approach front-end development in a simplistic way.

I'll update the documentation of the specific issues you mentioned or if you are willing a PR would be the best.

I would be happy to submit a PR if I can have a reference for how to approach it. The only thing I know at the moment is that most-probably it should be created in https://github.com/mint-lang/mint-website repo. If you ask me I would approach documentation like how https://ruby-doc.org/3.4.1 does. I would document keywords, syntax, etc and then in API for an individual module like Array demonstrate how it can be defined, manipulated, iterated etc.

I am also new to the language so I cannot consider myself in a position to know what pieces are really missing. In #793 (comment) I shared what I came across while experimenting with the language. That said few more thing comes to my mind which neither the Tutorial nor the Reference nor the mint-realworld app demonstrates

• how can we implement front-side validations. In web-apps even though server-side validations are expected to be in place, front-side validations cannot be ignored so the developers coming to Mint should know how to implement them just in case they are interested in giving a try to build the front-end of their legacy web-app using Mint.

• In the discussion Unable to use locally stored external CSS #790 I asked about how to use external CSS and you helped me solve it but that information is not available in the Reference. So it too should be documented. It helps developers like me who have just bare-minimum knowledge of working with CSS and JS and has experience working with popular CSS frameworks like Bootstrap and JS library like jQuery and more comfortable working with them whenever wanting to experiment with a front-end development framework/language.

Thanks.

[gdotdesign]

I would be happy to submit a PR if I can have a reference for how to approach it.

🙏

All documentation is in the mint-lang/mint-website repository, as you mentioned.

I think you could start with documenting the issues you had:

• Mentioning that stores are connected to a component if any of its states are referenced inside. This probably can be a section in the store page.
• let shadowing can be a section in the blocks page.
• Array manipulation. This can be in a new section specifically for teaching functional language concepts (not sure if in reference or guides, probably guides).
• Using external CSS. This can be a page in the guide.

I've put together a document for contributing to the reference section https://github.com/mint-lang/mint-website/blob/master/docs/Reference.md will do another for the guide and the API too.

If you need more information or a way I can help, let me know :)