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!
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…)