U - Write a linter ingredient handler for data.examples

[wbamberg]

The linter currently does check for the existence of an "Examples" section, but stumptown expects examples to have a particular structure, and the linter does not check that the content of the "Examples" section is in the right structure.

Acceptance criteria

The linter checks the correctness of the data.examples ingredient in recipes that include it, according to the specification agreed in mdn/sprints#3075.

[wbamberg]

I'd like us to consider whether the structure for examples described in the specification doc is unecessarily strict.

In the specification, everything that isn't actual example code (including explanatory prose) has to be corralled into the start of the example, and there may be only one code block (for each language) containing example code.

Looking through some JS pages, I think many examples will fail this test. For example, it means you can't intersperse prose and code, as in this example for String.slice().

For examples that aren't live samples, there's no functional reason to impose these kinds of limitations. Meaning, there's nothing about them that is needed by structured Markdown as we have envisaged it. We should still I think mandate that each example lives in H3 sections with titles, but apart from that we could just treat each example as unstructured prose. So here the key question seems to be: is there any non-functional reason to impose these restrictions? Meaning, would the added consistency help users, or would these restrictions make the examples worse, by restricting writers too much?

My inclination at this point is that we should relax these restrictions, and say:

• for all examples, each example must live in its own H3 section
• for non-live samples, there are no particular restrictions beyond that

For examples that are live samples, I think the situation is a bit different. I would like to avoid the KS-style approach where we have to embed directives in the example to say where to put the output iframe, and I would like to avoid having lots of extra markup in the example to say which bits of code are included in which live example. So I would suggest we could say:

• a single example may only contain one live sample
• the output of the live sample must always appear at the end of the example, after all the prose and sample code
• all code samples in an example section must be part of the live sample (we could fairly easily drop this restriction, and have writers add a class to the "code fence" for code samples to indicate that a particular code block is part of the live sample. But I think it would make things more complicated to maintain). An easy-to-check way to enforce this in Wiki reference pages would be that the ID argument to EmbedLiveSample must be the H3 section's ID.

In this model it would still be possible to intersperse code and prose, if people want to do that.

I'm sorry, I know it feels like we've been over and over this. I think it's inevitable though that our views on these kinds of issues will change as we look at more docs (and I wouldn't be surprised if this continues to happen). Note that the JS docs contain almost no live samples, but CSS contains many, so it's quite possible that we'll have to reconsider again when we get into that.

What do you think? @chrisdavidmills , @Elchi3 , @ddbeck ?

[ddbeck]

For the non-live samples, that makes sense to me. It's prose with explanatory code snippets. Seems reasonable you might want to intersperse commentary.

For the the live samples, I think this makes sense, except I'm not sure what you meant here:

In this model it would still be possible to intersperse code and prose, if people want to do that.

"This model" being live samples? Or being the whole set of restrictions on live samples and non-live samples taken together?

[wbamberg]

In this model it would still be possible to intersperse code and prose, if people want to do that.

"This model" being live samples? Or being the whole set of restrictions on live samples and non-live samples taken together?

"This model" was supposed to refer to the model for live samples, but it would apply to both live and, er, non-live. Both sorts would be able to intersperse code and commentary.

[ddbeck]

OK, that helps, thank you. I'd say it's OK to relax the restriction. Given how complex live samples can be, I'd like to keep the no-interspersed-prose restriction for them, but maybe that's needlessly confusing for authors, at least at this stage. And I suppose there's nothing stopping us from tightening the restrictions later.

[wbamberg]

I'd like to keep the no-interspersed-prose restriction for them

We can choose to do this if we want. I guess the main point here is that we don't need to: it would be quite easy to support live samples in this more liberal option. So this is purely a choice of what we think would be better - and I'm quite undecided about this. Perhaps seeing more pages will help sharpen our judgement here.

One factor pointing towards being more liberal though is: the more restrictive we are, the more work there is going to be in reworking content, and the more persuading we need to do that these restrictions are desirable.

[ddbeck]

No, it's fine. I just need to let go of scraping as a priority right now. 😆

[chrisdavidmills]

@wbamberg I've read this now, and I agree with it. Having such restrictions on non-live samples would be needlessly confusing and restructive.

this paragraph caught my eye:

all code samples in an example section must be part of the live sample (we could fairly easily drop this restriction, and have writers add a class to the "code fence" for code samples to indicate that a particular code block is part of the live sample. But I think it would make things more complicated to maintain). An easy-to-check way to enforce this in Wiki reference pages would be that the ID argument to EmbedLiveSample must be the H3 section's ID.

I think this also makes sense — a number of times in my MDN writing, I've wanted to have a live sample in a section, but then also have blocks of code that are not included in the live sample. There are reasons to want to do this, but it inevitably ends up in a combination of weird visual hacks, and hidden titles and sections, and code blocks that don't have formatting applied (which someone later on "helpfully" adds formatting to, breaking the live example in the process).

It would be so much easier just to enforce a rule of having to contain a live sample in its own subsection. In most cases you can find a way to make this work gracefully, but at the very worst you can just have all the explanation and non live blocks in the main section, and just have the live sample under a "Live sample" subheading at the end of the section.

[Elchi3]

I'm sorry, I know it feels like we've been over and over this. I think it's inevitable though that our views on these kinds of issues will change as we look at more docs (and I wouldn't be surprised if this continues to happen). Note that the JS docs contain almost no live samples, but CSS contains many, so it's quite possible that we'll have to reconsider again when we get into that.

This is exactly my feeling about this. I think we learn so much by actually working with a lot of content. That said, I'm in favor of relaxing restrictions for non-live samples for now and see how it goes.

[wbamberg]

-> #401