We need a cheat sheet or high level reference document

#1

I’m coming back to Dhall after a bit of a break and know that some things have changed. Interestingly, this is putting me back in the new user boat, and I’m surprised we don’t do a good job of the 1000ft picture. What I was specifically interested in was the defaulting syntax, but after a few minutes of hunting through dhall-lang.org, I couldn’t find it. In fact I still haven’t found it. We can do better than this!

I don’t have a concrete proposal, but I think we need to make it very obvious what the syntax of Dhall is. As an example, I regularly use this cheat sheet for Alloy: http://blackmesatech.com/2013/07/alloy/slides/cheatsheet.landscape.xhtml. Alloy is probably a smaller language, but this shows me almost everything I need to know.

I think we should produce something like this and make it very easy to reach from the homepage. Linking to an ABNF or formal specification is the wrong level of detail. I’m a human, not a computer!

Thoughts?

2 Likes
#2

Are you aware of this cheatsheet? https://docs.dhall-lang.org/howtos/Cheatsheet.html

#3

No. This looks good, though - could it be linked to directly from the homepage?

#4

Agreed. Had very hard time finding a way to import a default dhall file and overwrite its values for few fields.

Another thing I’d like to see is a way to create a new datatype data Mode = Live | Debug and use it (as import as well).

I’ve figured out both, but it wasn’t easy.

#5

@ocharles: The home page links to the cheatsheet under the “How-to guides” drop-down

#6

I could probably PR such a change but as a matter of feedback if I am not mistaken the with keyword is not explained in the cheatsheet. It is also an idiom that is a bit unusual (it doesn’t bring any bell for me) and searching for with on the documentation site is not … convenient.

dhall2020-06-11_23-07-38
dhall2020-06-11_23-07-381370×461 27.1 KB

#7

I want to add that this is still an area where Dhall is weak. Trying to onboard new contributors to our internal Dhall-based codebases is getting internal pushback. In normal times, new contributors would be able to just refer to senior contributors to get their bearings or to get newbie-type questions answered; however, with new contributors working from home due to COVID-19, this feels less natural and new contributors are often relying on the website and Google searches instead.

My suggestion would be to simplify the dhall-lang.org website, to replace the drop-down menus for Discussion, Tutorial, How-To Guides, References with a single link to the documentation at docs.dhall-lang.org. For example, as a new user, going to the website, clicking References -> Grammar and getting directed to the ABNF is not very friendly - “Grammar” for a new user is often more closely related to questions like “what does Foo:{=} mean?” and the documentation does a better job of hiding the ABNF behind “Machine-readable specification of the Dhall grammar”.

1 Like
#8

It’s good to hear that the cheatsheet is linked, but my initial comment about spending minutes to find it was not an exaggeration, so I wonder if we need to make it more prominent.

#9

@ocharles: I think at this point the discussion will go more quickly if somebody puts up a pull request with a suggested change. Instructions are here:

The reason I suggest this is that there are essentially two main approaches to addressing this request:

  • Try to add a link to the cheatsheet in the top bar, which currently already has limited real estate
  • Restructure the page to organize how we present things differently

For either approach I think the devil is in the details and would be best be done by putting forth a proposed change to the page rather than trying to communicate the idea in prose.