I've been trying to teach some older non-technical users how to use TOML front-matter for a simple recipe site that I'm putting together. This front-matter might look something like this:
[extra]
title = "Traditional \"Scottish\" porridge"
description = """A traditional Scottish version of porridge made using
water and salt.
If you need instructions on how to make porridge, you're probably not a
traditional Scot. ;-) We recommend milk instead of water in that case.
"""
servings = 1
prep-time = "5 minutes"
ingredients = [
"40 g oats",
"250 ml water",
"pinch of salt",
]
directions = [
"Add all the ingredients to a saucepan.",
"""Stirring frequently, cook on a medium heat until the porridge thickens
and becomes...porridgy.""",
"Serve.",
]
[extra.nutrition]
fat = "1 g"
carbs = "30 g"
protein = "4 g"
I've had quite a lot of trouble getting them to feel comfortable with this, so I tried them with YAML instead, which for comparison would be:
extra:
title: Traditional "Scottish" porridge
description: A traditional Scottish version of porridge made using water
and salt.
If you need instructions on how to make porridge, you're probably not a
traditional Scot. ;-) We recommend milk instead of water in that case.
servings: 1
prep-time: 5 minutes
directions:
- Add all the ingredients to a saucepan.
- Stirring frequently, cook on a medium heat until the porridge
thickens and becomes...porridgy.
- Serve.
ingredients:
- 40 g oats
- 250 ml water
- pinch of salt
nutrition:
fat: 1 g
carbs: 30 g
protein: 4 g
There are a bunch of issues with the TOML (demonstrate in the TOML example above) that when taken together are making them really unhappy:
- In general there's a bunch of syntax that non-technical users aren't used to dealing with.
- As a programmer, quoting text seems normal to me, but to them it seems like an unnecessary irritation and visual clutter.
- The need to quote text also means that they would need to remember to "escape" quote marks using a backslash, and that probably isn't going to happen. :-/
- Requiring different quoting for single line text and multi-line text (triple quotes) seems to them to be gratuitous, and will likely be error prone.
- For lists of strings, in addition to the quoting, adding in the idea that trailing commas separate list items, and that square brackets have to "wrap" a list isn't going down well. They much prefer to forget all that and just begin each list item with the intuitive looking "-" marker used by YAML.
- Getting more nitty now, but they also don't like the use of "=" to associate values ("its not maths"), and prefer ":".
They find the YAML considerably cleaner/less confusing/more intuitive, and now that I've shown them that they simply can't understand why anyone would use TOML. (Which, for our schema and usage scenario, seems valid.)
YAML of course isn't without issues. Specifically I'd be worried about the potential for them to mess up the (semantically significant) indentation. However, they're pretty adamant that if that's the only thing they'd need to worry about then they could get that right, and that YAML would be by far the better choice for them. (In fact - if I'm going to ask them to enter their recipes in a text format - they think the indentation would be a good thing, since it makes things more readable.)
done in pr