More brainstorming for changing the dhall-lang.org landing page


#1

There are two changes I’d like to propose:

  • Change the tag line to “A lifesaver for templating YAML”

    The focus on “templating YAML” is inspired by a suggestion by @singpolyma previously in Idea for a slight rebranding change. Most people who use Dhall and put up with its unfamiliar syntax do so because they need to template configuration files in a way that isn’t terrible.

    In other words, they don’t need to replace YAML in general (because sometimes TOML would be a better alternative for some YAML configuration files). They very specifically want to replace their existing YAML template solution (such as Helm).

    This change also includes the metaphor of a “lifesaver” instead of saying “non-repetitive alternative to …⁢”. I propose this because:

    • “Lifesaver” suggests a metaphor that people are “drowning” in bad YAML templates and need a lifesaver to stay afloat
    • People culturally associate a “lifesaver” with “minimum required level of safety” which promotes the perception that the safety assurances Dhall provides are non-negotiable
    • The tagline puts words into people’s mouths by suggesting as literally as possible how they should evangelize Dhall to each other (e.g. “Dhall was a lifesaver for us”)
    • It fits with the nautical theme of the Kubernetes ecosystem (which I am targeting as a mainstream entrypoint by building towards Dhall as a Helm replacement)
  • Change the “Human Friendly” section of the dhall-lang.org to “Safe templates” or something similar

    The idea is that we want to illustrate how Dhall’s templates always generate correct-by-construction output (i.e. it is not templating Text)


#2

My biggest concern with this is that, even more than the current “The non-repetitive alternative to YAML,” it seems to extremely limit Dhall’s scope/usecases to the unfamiliar person (who is presumably what this is being written for). If I had stumbled across “A lifesaver for templating YAML” I would never have given Dhall a second look, because I don’t need to template YAML, nor will I ever. Perhaps “template YAML, JSON, or even [plain]text!” or something?

Plus this becomes kind of confusing when the next line says “you can think of as: JSON + functions + types + imports.” Is it YAML? Is it JSON? Something else? If I see something sold solely for the purpose of “templating YAML,” JSON-style syntax is not what I’m going to immediately expect.

On an unrelated note, would it be worth making “Dhall is a programmable configuration language” to something like “Dhall is a programmable, type-safe configuration language?” I think type-safety is a selling point, since it essentially does away with the need for schema/validation.

Just my two cents as someone who recently stumbled across the language.


#3

Who do you view as the target audience, Gabriel?

I remember that this was an important aspect when FPComplete made its own Haskell landing page – it was targeted more at the CTOs than at the programmers.


#4

@SiriusStarr: How about: “A safe templating language?”


#5

@Gabriel439 That gets both to type safety and the fact that it’s not Turing complete (and thus safe to import stuff from untrusted websites), so I like it.

Maybe “templating and configuration language” though, since it does more than just templating?

And is dropping the “programmable” good or bad? It should be immediately obvious that it’s programmable, but…


#6

Slightly less static, but could also make it change through multiple lines, like:

“Dhall is…[ ]”

And then what’s in [ ] changes every couple seconds through like:

  • a lifesaver for templating YAML
  • a safe templating language
  • a programmable configuration language
  • the answer
  • like JSON + functions + types + imports
  • pure and functional
  • etc etc

Which would maybe get at the diversity of applications of the language (and at least one of them is probably going to catch your eye).


#7

@sjakobi: The target “buyer” is a technical leader, typically in DevOps or somebody who maintains shared infrastructure. Specifically, somebody who has sufficient credibility within the organization to incorporate Dhall into their team’s or company’s deployment pipeline. This will typically be the person responsible for evaluating new technologies, and doing requirements gathering design for new projects. This person will definitely be technical, possibly an individual contributor or possibly an architect. They will likely be part of an organization of at least 20+ engineers that is noticing significant configuration drift due to repetition. Common problems that this person struggles with are:

  • Making sure that dev/staging/prod share common configuration options
  • Keeping resource specifications (such as CPU/disk/RAM/ports/hosts) synchronized across programs written in multiple languages
  • Reducing boilerplate for each new component that needs to be built so that people don’t just keep adding unrelated functionality into existing components
  • Training junior developers to properly and idiomatically use internal tools instead of copying-and-pasting from examples
  • Keeping the deployment pipeline’s “footprint” as lean as possible so that it is easier to document/maintain/repave

#8

@SiriusStarr: I’m fairly certain that we should not dilute our message. This is something covered in detail by the book Crossing the Chasm, but I can summarize it here.

You want to focus on one narrow area when marketing your “product” because you need to reach a certain critical mass of users to trigger a viral chain reaction where recommendations spread by word of mouth. If you “play the field” then you never reach that necessary critical mass of users necessary to keep that positive feedback loop self-sustaining.


#9

@Gabriel439 Gotcha; you’re the boss. I’m just offering my two cents as someone who only fairly recently discovered Dhall and would never have found it if it were being billed as a YAML templating tool. There may very well be huge demand for just such a thing; not my area of expertise, haha.


#10

@SiriusStarr: So I’ve been trying to think of the right choice of words to not suggest that Dhall can only be used for templating (i.e. it can be a configuration format in its own right). Maybe something simple like:

“Maintainable configuration files”

That makes clear who the target audience is: somebody struggling with configuration files. It also makes clear what the innovation is: maintainability. Maintainability then justifies the choice of language features:

  • Functions - Code is easier to maintain if you don’t repeat yourself
  • Imports - You need a module system for projects that exceed a certain size
  • Types - Types make refactors safe and easy

#11

@Gabriel439 I like that a lot, since it applies to basically every conceivable usecase, whether templating or using Dhall directly. And I would break out those bullet points explicitly like that to spell it out for people.

I suppose dhall text is sort of the one thing left out by this, but that’s a pretty fringe thing (even though it’s what I use the most).


#12

I’ve thrown together some ideas from this thread and the older brainstorming thread in an unstructured way on figma: https://www.figma.com/file/TzpIkJ98qRsKQ8gy0SJJQK/Dhall-Landing-Page?node-id=0%3A1

This is obviously far from a finished design for a landing page, but it might be nice for coordinating some brainstorming!

Feel free to edit this file, anyone with the link can edit it. There is a git-like history, so even if you mess something up - no problem! (Also, there’s Ctrl+Z :wink: )

Figma could also be used to create a final design for the landing page. Something to show to people to gather feedback before having to implement it tediously using html and css.

I might pick up designing the website as an exercise for myself just for fun. I’ve designed some personal things before and I can believe I can do better than the current design aesthetically, but I’m not a professional designer, so there is a possibility I won’t come up with anything good.


#13

I think the two things that Dhall “is” to most people are:

  • Templating
  • Structure

So saying just “safe templating” seems to miss out on talking about how this is structured templating (not just advanced string interpolation). But saying YAML, while it does convey the structure, also limits peoples minds to thinking about generating YAML files (and maybe not other formats, or better yet, using Dhall directly).


#14

So I think if we change the major “bullet points” to follow the maintainability theme, here are some initial ideas I had while brainstorming:

Don’t repeat yourself

Struggling with configuration drift? Keep your infrastructure in sync by creating a single source of truth that you can reference everywhere.

Highlight the following features: functions, imports, and multiple integrations

Fearlessly refactor

Need to clean up a big mess? Dhall provides built-in support for static types and change control so that you can move fast without breaking things.

Highlight the following features: types, dhall hash (to verify that a change was behavior-preserving), dhall diff (to verify that an intentional change had the expected effect)

Safety first

Sick of Turing-complete configuration languages? Dhall is a total functional programming language that forbids arbitrary side effects, so the language can never fail, hang, crash, leak secrets, or compromise your system.

Highlight here: non-Turing-complete, semantic integrity checks, pre-normalization, CORS, XSS protection, same origin policy


#15

@matheus23: Also, whenever you feel ready to make changes to the website the code for that lives here:


#16

This is really useful for potential website content!

Another thing I was thinking about: We could go with a structure similar to rust’s landing page. They have subpages for different applications rust it is good at. So there is another small subpage for webassembly, command line applications, embedded systems, etc.

My suggestion would be to have a kubernetes sub-page showing off useful projects/dhall features for the kubernetes application especially with a prominent link to it on the main page.

What @singpolyma’s said about a too-narrow dhall description resonates with my gut feeling:

Having two pages keeps dhall open enough on the main page, but anyone interested in using dhall for kubernetes configuration can quickly find a good place to start.


#17

I’ve been looking around various landing pages for programming languages. For anyone who wants to do that as well, here are some noteworthy landing pages:

https://clojure.org/


https://www.elm-lang.org
https://racket-lang.org
https://www.scala-lang.org/
https://haskell.org
https://fsharp.org/

https://www.ruby-lang.org/en/
https://www.unisonweb.org/

Looking at these examples, I think we should mention that dhall is purely functional as that might not be obvious to newcomers. Scala, haskell, fsharp and clojure seem to advertise this. (Counter-argument: elm and racket don’t seem to advertise it).


#18

Well, these are general-purpose languages, but Dhall isn’t one. It might be more fruitful to compare it with languages in a similar space like https://jsonnet.org/ or https://cuelang.org/.


EDIT: …or Nix: https://nixos.wiki/wiki/Nix_Expression_Language


#19

@matheus23: Even for general purpose languages, I don’t think pitching in terms of “functional” convinces enough people to switch.

I find that an effective guideline when drafting a pitch is to frame technology choice in terms of how it effects people’s careers (because most mainstream programmers are career-oriented when evaluating which new technologies to invest in).

As a simple example, you might sell Elm to a JavaScript programmer like this:

Do you really want to spend the rest of your career debugging “undefined is not a function”?

… or for Dhall advertising to an Ops person:

Did you really dream of becoming a “YAML engineer”?

The reason why this approach works is that people are more likely to take leaps of faith on new technologies when they evaluate the cost of poor technologies across a larger time span (i.e. their entire career).


#20

Yes. I wouldn’t pitch Dhall as a functional programming language, but I would like it to be mentioned.
(I think) most people already can already get more of an idea about what Dhall is when they hear ‘functional’: They will expect to see things like mapping or folding. To me this is equally as important as “Strong Types”: From this they I expect them to envision something like Optional.

To be clear: I’m not talking about “functional” being a selling point. But I think the webpage shouldn’t only contain selling points, but also simply a description of what Dhall is. I imagine someone coming to a landing page would like to see at least one sentence similar in style to a wikipedia page.

I think the first sentence of Elm’s wikipedia page is amazing:

Elm is a domain-specific programming language for declaratively creating web browser-based graphical user interfaces. Elm is purely functional, and is developed with emphasis on usability, performance, and robustness. It advertises “no runtime exceptions in practice”,[6] made possible by the Elm compiler’s static type checking.

(I couldn’t find a close example to Dhall: jsonnet and cuelang don’t have a wikipedia entry, and I don’t particularly like the first sentence of nix’s entry.)