I just tried Elm (nothing too complicated, just wanted to make a POST request to get a token and then use the obtained token to GET a list of strings).
It wasn't a pleasant experience – not because of the language, but because of the docs. Specifically:
the docs didn't go beyond the obvious things (e.g. I couldn't find how to add headers to a request)
I confused elm-core/http and evancz/http, because a) they were named in the same way, b) had same module names, and c) Evan is the author of Elm
the docs had no “since” annotations (e.g. beginnerProgram is exported from Html in 0.18 but apparently not in 0.17)
However, there were some nice things as well:
linked identifiers in code
examples which I could just copy and use (though if http://elm-lang.org/examples had more examples it would've been more useful)
So, I want the following things in Guide:
Linked identifiers in Haskell code blocks. No idea yet how to achieve this.
A mechanism for adding popups in Markdown – you click a dotted word, you get a popup. I'm not sure about it, but I think that it will make notes more accessible for beginners – the main text provides information, the popups provide explanations when needed without cluttering the main text. This would have to be tested, though, because there's a chance it would do more harm than good.
Notes should use tabs (will add a sketch later). This will both solve the “can't edit one section” problem and let us pack more info into notes.
I want some kind of “example wizard”. For instance, there's a basic example – “how to make a request” – and then there'd be buttons like “show me how to make a JSON request”, “show me how to make a request with headers”, etc, and added/changed lines would be highlighted. Again, this lets us pack more info into examples. See #150
I just tried Elm (nothing too complicated, just wanted to make a POST request to get a token and then use the obtained token to GET a list of strings).
It wasn't a pleasant experience – not because of the language, but because of the docs. Specifically:
elm-core/http
andevancz/http
, because a) they were named in the same way, b) had same module names, and c) Evan is the author of ElmbeginnerProgram
is exported fromHtml
in 0.18 but apparently not in 0.17)However, there were some nice things as well:
So, I want the following things in Guide:
Linked identifiers in Haskell code blocks. No idea yet how to achieve this.
A mechanism for adding popups in Markdown – you click a dotted word, you get a popup. I'm not sure about it, but I think that it will make notes more accessible for beginners – the main text provides information, the popups provide explanations when needed without cluttering the main text. This would have to be tested, though, because there's a chance it would do more harm than good.
Notes should use tabs (will add a sketch later). This will both solve the “can't edit one section” problem and let us pack more info into notes.
I want some kind of “example wizard”. For instance, there's a basic example – “how to make a request” – and then there'd be buttons like “show me how to make a JSON request”, “show me how to make a request with headers”, etc, and added/changed lines would be highlighted. Again, this lets us pack more info into examples. See #150
Maybe there's more.