Comprehensive Elm docs site

[Janiczek]

Hello!

Lately I’ve been thinking about Elm documentation and these two blogposts:

• https://www.divio.com/en/blog/documentation/
• https://jacobian.org/writing/what-to-write/

I wonder whether there would be a general interest to make our Elm docs better. If I adopt the terminology from the blogposts, that might mean consolidating some resources we already have into a central place:

Tutorials

Stuff like building Counter and RandomGif, step by step, from the “I don’t even have Elm installed” to “Yay, it shows me cat pictures!”

How-to guides

Stuff like:

• adding a port doing element.scrollIntoView() to an Elm application
• creating a JSON decoder for some API, etc.

Reference

That would be probably both package docs AND docs for the language itself.

Judging from posts like this one, we could probably make that second one a bit better?

Explanations

Why is stuff in Elm done the way it is. Context, history, perspective. What Evan talks and writes about. What advantages and disadvantages does it bring. How to think about stuff.

---

Do you think this would be a good thing to have? To clean the onboarding and developer experience a bit? Somewhere like docs.elm-lang.org? (I was playing with the idea of buying an elm-docs.com or elm-learning.com domain, but haven’t bought anything.)

[gampleman]

I think centralizing all this would be fantastic.

I also would love if the official package website supported these kinds of documentation types for packages. Right now it supports only README and API docs which tend to be mostly reference or occasionally a basic howto.

However for many packages having guides and explanations would be very helpful.

[mbuhot]

You may like to draw some inspiration from the Elixir ecosystem which has generally very good docs.

https://elixir-lang.org - installation and language tutorial, links to other resources

https://elixirschool.com/ - another in depth language and common library tutorial site

https://hexdocs.pm/ - package docs with API reference and additional guides for each package, eg phoenix

[mgold]

Well there is the official Elm-lang guide.

There was also the elm-guides/elm-for-js project, which fizzled out about two years ago, despite an elm-community fork.

I think what the latter tells us is start writing the documentation first, and find a home for it later. If that’s having a docs folder in a repo with markdown files, start there.

[Janiczek]

Right, “facta non verba” is probably the way to go here.

I’ve started braindumping topics into a Trello board, and got the Elm Slack export to see what questions most frequently get asked on #beginners, #help, #general and elsewhere. Will probably go with some kind of Jekyll site - as low traction as possible.

Also, holy moly, @mhubot, those Phoenix docs are something else!

[Janiczek]

Started a GitHub repo and page:

elm-docs

Janiczek/elm-docs