Style guide

[patik]

A comment in #40 got me thinking that the recipes could easily be more machine-readable:

[The automatic indexer] wouldn't be able to figure out which recipes are vegetarian unless noted somewhere in the recipe that the extractor could find [...]

Having a bit of structure in the recipe files would allow us to treat the recipes more like a database from which tools can draw. For example, an app could allow a user to say "I have ingredients x, y, and z" and it lists the recipes that can be made.

I wouldn't want to overcomplicate the process of writing recipes—after all, plain text makes it easy for anyone to contribute. Perhaps there can be a balance between ease of writing and parse-ability.

For example, each recipe could contain the following:

• A level-1 header containing the title
• A level-2 header called "Ingredients" followed by a list of ingredients
• A level-2 header "Notes" followed by a list: whether or not the recipe is vegan, prep time, cooking time, etc.

The author could add any other free-form sections they'd like.

Thoughts?

[knowtheory]

I thought about that. There's an hRecipe microformat for example. I think that it's not worth it.

It should be as easy as possible to add and modify recipes. It should be as easy as writing markdown. And if their stuff happens to be easily scrapable, then awesome. If not, shrug. Someone can massage it later or whatever.

That said, if people wanted to make writing processing scripts easy do the following:

1. Ingredient lists should use bullets: *
2. Steps in the recipe, if in list form, should be numbered markdown lists.
3. The recipe name should be the first thing in the file.
4. One recipe per file (this is actually probably more controversial than it seems at first blush).

[patik]

I agree that hRecipe is overkill for this repo. When I get a chance I'll go through the recipes and format them a little more consistently, but nothing more complicated than headings and lists. I can combine our guidelines and put them on the wiki as well.

[dansinker]

So I think that Ted's put it pretty well: there's a natural push-and-pull between humans and machines here. We want humans to be able to submit as easily as possible, which means that it's going to be harder for machines to read this stuff, because humans often don't follow directions.

I definitely bias towards ease-of-submission. Yesterday I had four or five people say that they learned some git basics just to be able to submit. And I'd say 1/3 of the recipes came in with no formatting, 1/3 with decent markdown, and 1/3 with made up formatting.

So there's probably manual processing somewhere along the way no matter what

That said, when we added the index yesterday and then added on the readme that people needed to update their thing into the index, we saw about 50% people following that direction pretty much immediately.

So having good, clear, formatting guidelines is a good idea, and I'm all for some lightweight standardization, but I don't really think that we should fall too far toward making for machines.

[riverfr0zen]

Yes, unless we (as a species) dedicate ourselves to transhuman ideas, we're all still pretty much human, so let's keep it that way.