Consider using recipes to represent element-specific attributes

[wbamberg]

From the writers' guide PR:

@Elchi3 :

Personally, I don't like that much how attribute md files are different from say the main element md file, but this is where we're at right now. Can you maybe describe a bit how these md files are different and not really "pages". It would maybe also help me to better understand why we made it this way.

@ddbeck :

This is a good point, Florian. And it suggests to me that we might use recipes for HTML attributes too, but use mdn_url as a way to signify that some content is addressable (and should get a page generated) and some content is a partial component (that shouldn't get a page generated). In our recipe metaphor: lots of desserts use meringues, but nobody serves a meringue by itself.

[wbamberg]

At the moment, the situation is like this:

• for every file in /content with a recipe property, build-json makes a standalone JSON object saved as a file into /packaged.
• for every file in /packaged, the renderer builds an MDN page (actually the renderer might already filter on mdn_url, I'm not sure)

So the story is quite simple. You have recipes for files that want to be MDN pages, and the build process turns each one into a JSON file, and the renderer turns each JSON file into a page.

If we want to "use recipes for HTML attributes too, but use mdn_url as a way to signify that some content is addressable (and should get a page generated) and some content is a partial component (that shouldn't get a page generated)", then how does that affect this process? We might say:

• for every file in /content with a recipe property, build-json makes a standalone JSON object saved as a file into /packaged.
• for every file in /packaged that contains mdn_url, the renderer builds an MDN page

But also, recipe-generated objects can embed other recipe-generated objects. So we need some syntax allowing an ingredient (in this case the attributes front matter property) to refer to a recipe. And some code that understand this, and when it sees a reference like this, it builds the object referenced (or retrieves it from a cache if it's been built already), and instead of writing it to a standalone JSON file, embeds the resulting JSON object in the embedding object?

What do we get in return for this? One thing is this: at the moment the rules for how attribute files are structured are kind of secret implicit rules, buried in the attributes ingredient docs. By using the recipe we are exposing the rules in a more consistent way, maybe.

But we should be clear that there will always be these kinds of ingredient-specific rules. For example, the rules about live samples are not going to be described in any recipe.

Which leads to another question: what's the test for whether a thing should be recipe-driven or not? At the moment it's simple: if it wants to be an MDN page. But under this proposal that doesn't work. We need to have a clear answer for this, otherwise why can't BCD tables or live samples be specified in recipes (I really don't think they should)? I think the answer is: self-contained documentation objects for web technology items can be recipe-driven. An HTML attribute is a web technology item, and the whole collection of documentation elements for it - examples, BCD, prose - are a complete documentation object for it. BCD is only one aspect of the documentation for an item.

Another very compelling argument for having recipes drive attributes is that we are proposing to do that for global attributes, and element-specific attributes are the same kind of thing. But this also makes me wonder, why do we have standalone pages on MDN for one and not for the other? That is, is this inconsistency in stumptown just a reflection of an inconsistency in MDN?

Before we make any big changes though, I'd also be interested in seeing other examples of this sort of problem: that is, items which should be recipe-represented according to the rule "self-contained documentation objects for web technology items", but which are embedded in other pages rather then built as standalone pages. I can't off-hand think of any, which makes me wonder if this is an aberration. A much more common way to handle relations between different "documentation objects" is just by linking between standalone pages. For example, consider a recipe-driven page for a JS object like Array. It has methods, which are other documentation objects with which we want to express a relation. But we're not going to do this by embedding them inside the Array page, and then having some custom rendering logic decide how to render methods when they are embedded. We'll do it by linking to the method pages, using the generic link_list ingredient that embeds a link and a short description.