Feedback on dhall-lang.org from a Reddit user


#1

In a recent thread on embedded scripting languages in r/haskell, user fridofrido mentioned that he didn’t find the dhall-lang.org website to be very clear. I asked him for specifics and he kindly responded with quite a bit of feedback that I hope we can use to improve the site! :slight_smile:

Here is his response to my question:

Well I looked it, and even though I heard quite a lot about this project before, and had a general idea what it is about, it was very confusing, and I couldn’t easily more details to refine (or revise) my previous knowledge

I think, first of all, every project web page should start with “what this project is about”. And I don’t mean big catchy colored sentences, but in no-nonsense language.

Like the first thing you see when loading the page is “Human-friendly”, then the second thing you see is “Turing completeness is not a feature” - ok but what the hell it is??? It’s only the third biggest thing, and even that is well hidden by the b&w colors and all the other noise on the screen, is that it is a “configuration language”. So that’s one thing.

Then I couldn’t really figure out what kind of type system it has (at first it’s not even clear it has a type system, but I knew that already). I still have no idea if you can even introduce new datatypes, though I know that it has polymorphism (but the only reason I understand what that is because I already know Haskell).

Then many of the introduction material is a long series, starting from something long and complicated which is not dhall, doing lots of transformations, ending after many pages in something which is actually dhall. I mean, yeah this is pedagogical, but before doing that, the reader should know what the hell is the goal. So I still have no real idea how the syntax even looks!

Then the home page links to the github page, so all of a sudden you are at a completely different page with different organization, different interface elements, different header (which is actually github’s header, but just one seconds before it was dhall’s header! In fact there are two new headers!). This is all very confusing.

Somebody looking it at first does not have the patience to go through all the material, they want to know what the hell this is about, and whether it has any chance of being a good fit to their problems.

And so on…

(btw all this is applicable to many many other software project pages too, unfortunately…)


#2

Like the first thing you see when loading the page is “Human-friendly”,

It looks like they didn’t see the live demo if that’s the first thing they saw. Maybe they disabled JavaScript?


#3

Apparently not:

The live demo was filed under “other noise on the screen”. I’m not in the camp which thinks a language start page should contain a live demo. Maybe a link to a live demo, that’s fine.

But why would I want immediately try a language I don’t even even know the syntax of? If you look from that viewpoint, it’s nothing more than a small set of (mostly trivial) examples. Maybe it’s a good way to learn for some people, but probably not a good fit for all people.

Anyway I admit that I didn’t spent too much time on the page, but I found the way it was organized very frustrating. YMMV.


#4

I think it’s better to continue the conversation on that Reddit thread rather than mirroring it here.