elm / browser

Create Elm programs that run in browsers!
https://package.elm-lang.org/packages/elm/browser/latest/
BSD 3-Clause "New" or "Revised" License
312 stars 64 forks source link

Developer experience: Not always clear how to init from JS #122

Open cmditch opened 3 years ago

cmditch commented 3 years ago

I appreciate how much effort and focus the Elm community devotes to clear & thorough documentation. In an effort to continue improving the docs, I'll go over an experience I recently had trying to use Browser.sandbox for a SSCCE.

I found that it was not very clear from the Browser.element or Browser.sandbox docs how to initialize them within JS.

I spent quite a bit of time pouring over the package docs, elm guide, and elm guide examples to no avail.

I eventually happened upon https://guide.elm-lang.org/interop/ , which shows the use of the node field, but it's not clear when this field is relevant wrt sandbox, element, document, application. I also found https://guide.elm-lang.org/webapps/, but this only shows how to init a document.

Potential ways to ameliorate this confusion:

  1. Include js snipptes in the Browser docs.
  2. Include js/html snippets in the guides examples instead of only pure Elm.
  3. Include something like the table below as a quick and clear reference in the Browser docs and Elm guide (with help from @Janiczek).
    +----------------------+-------------------+------------------------+
    | entry point js param | uses `node` field | supports `flags` field |
    +----------------------+-------------------+------------------------+
    | Platform.worker      | no                | yes                    |
    +----------------------+-------------------+------------------------+
    | Browser.sandbox      | yes               | no                     |
    +----------------------+-------------------+------------------------+
    | Browser.element      | yes               | yes                    |
    +----------------------+-------------------+------------------------+
    | Browser.document     | no                | yes                    |
    +----------------------+-------------------+------------------------+
    | Browser.application  | no                | yes                    |
    +----------------------+-------------------+------------------------+
  4. All of the above
  5. None of the above and something better?

Thanks! Coury