Convert Elm's official guide into OCaml

[jackalcooper]

We need a proper getting started for forks didn't have Elm background. For now I think it is a good idea to convert the official guide from Elm. If Reason version is included, it would be even more ideal. Here is the guide: An Introduction to Elm

[OvermindDL1]

I was thinking of the same. :-)

It might be best to not base it on Elm's guide precisely (I don't know the license of it yet), and I'd definitely want a Reason format as well, preferably in the same file with a toggle button floating in the top-right or so if javascript is enabled and/or a table showing both forms in both syntax's side-by-side if no javascript (or all the time?).

Any ideas for a good documentation engine? I'm leaning toward whatever Rustbook uses as it is clean and fast generated HTML that drops down to be fairly mobile friendly, however that would add another dependency (only for the docs), or are there any good node-runnable ones?

Should it be in the same repository as here (I'm leaning yes so I can push new Tea versions and update docs in one command, but overall undecided) or a sibling repo?

[jackalcooper]

if javascript is enabled and/or a table showing both forms in both syntax's side-by-side if no javascript (or all the time?)

This sounds good. Plus if we got to know how to make the compiler run in browser like BuckleScript's official website, we can run the code example and present the DOM like Elm's Ellie?

Any ideas for a good documentation engine?

No idea. My favorite doc is Elixir's because it has elegant design and good support for mobile. Rust's looks cool. Rust has the support to "run" the code as well.

Should it be in the same repository as here

Yes, BuckleScript's repo includes the doc as well. But I has no idea about where to add the dependency of the doc engine.

[jackalcooper]

We should also include a HTML to VDOM code generator (in the doc website maybe?). Currently I'm using one I wrote in Elixir (it is so easy to write it with pattern matching) so it doesn't run in browser without backend. Oh a JSON decoder generator is needed as well. These two improve the productivity a lot.

[tcoopman]

I would also like it if the documentation is part of the repo. About the format and tools, I can't offer a lot of advice, but I think it should be something that is easy for others to contribute to.

[OvermindDL1]

This sounds good. Plus if we got to know how to make the compiler run in browser like BuckleScript's official website, we can run the code example and present the DOM like Elm's Ellie?

Except in real-time without server-side generation, I've definitely wanted that yep! :-)

We should also include a HTML to VDOM code generator (in the doc website maybe?). Currently I'm using one I wrote in Elixir (it is so easy to write it with pattern matching) so it doesn't run in browser without backend. Oh a JSON decoder generator is needed as well. These two improve the productivity a lot.

Hmm, elaborate?

I would also like it if the documentation is part of the repo. About the format and tools, I can't offer a lot of advice, but I think it should be something that is easy for others to contribute to.

Absolutely so! :-)

[feluxe]

Any ideas for a good documentation engine?

I currently have these two opened in the browser to get started with reason and bs-tea ;)

https://reasonml.github.io/docs/en/quickstart-javascript.html https://bucklescript.github.io/docs/en/installation.html

Some nice documentation, IMHO.

I think they use this engine:

https://github.com/facebook/Docusaurus

It would be good to align with the other Reason projects, I guess.

[OvermindDL1]

I think they use this engine:

Ahh, I didn't know what they used, I just knew it wasn't the standard ocamldoc... ^.^;

Thanks for the link!

[ankhers]

Have you decided on a documentation engine for this project? Also, just in case you haven't seen, the elm guide license is here. I could be wrong, but I think the "NoDerivatives" part would prevent us from doing a copy / paste with ocaml and reason syntax.

[tcoopman]

It can be useful to reach out to and ask if it would be ok to use it. Also, this might be worth a look: https://jaredforsyth.com/docre/index.html

[OvermindDL1]

I'd probably just use a normal ocaml documentation engine, that way it would integrate properly and not get out of sync as easily.