Interactive examples for CSS - keep the "static examples" or not?

MDN
#1

I’ve been thinking about exactly how we should update CSS pages with interactive examples.

In particular: the current pages contain a code block at the start, which provides example syntax. For example, the first code block here: https://developer.mozilla.org/en-US/docs/Web/CSS/background-repeat.

I had been thinking that the interactive examples would just make this redundant, so we should remove it, as in https://developer.mozilla.org/en-US/docs/Web/CSS/filter, for example.

But now I’m updating a few more pages, I’m seeing that in some cases at least, the static block adds some useful information:

  1. it’s not constrained to 6 options, so for more complex syntaxes it can show more variations.

  2. it often describes the syntax form in a comment, which is helpful.

So perhaps it would be good to keep this block, but move it to the start of the “Syntax” section, where it seems to fit well: https://developer.mozilla.org/en-US/docs/Web/CSS/background-size. Then the “Syntax” section seems to provide a nice progression of syntax explanation, from example syntax, to text description of the syntax, to formal syntax.

But there’s definitely an argument that this is redundant, especially for properties that have very simple syntax. (I don’t think redundancy is terribly bad: it’s OK, IMO, for docs to explain the same thing in different ways.)

We could only include the block where it seems to be not-redundant, but then the pages are inconsistent, and consistency seems valuable for reference pages.

So I’m interested in opinions:

1 Like
#2

I think we should keep it, moved down to the Syntax section, since as you point out, it can include more scenarios than the interactive examples. I feel that occasional redundancy is not inherently a bad thing, and that the consistency of always including it is more important than avoiding some degree of repetition.

Eric Shepherd
Senior Technical Writer

MDN Web Docs: https://developer.mozilla.org/

Blog: http://www.bitstampede.com/

Twitter: http://twitter.com/sheppy

1 Like
#3

I agree with sheppy. Having the example syntax block at the top of the Syntax section, before the other sections, would work well.

1 Like
#4

Each kind of presentation serves a different audience. Thus unless there is a strong argument against inclusion (abridgement?), each kind is useful and should be retained or added.

An exhaustive list of syntax variations is… exhausting, and can actually dissuade the reader from continuing, which is not what you want at the beginning of an article.

It would be most useful within the syntax section. And it is most complementary alongside the Formal Syntax subsection. Non-CS people have difficulties with decoding formal syntax, especially with walls as in your filter example. They will be more comfortable with the many samples in a list of variations. And the list is amenable to ‘scanning’, which is why it was put up top to begin with? (but where it often overwhelms now)

I’m thinking the only real question is what ordering for subsections “Syntax” (longhand variations list), “Values”, “Formal Syntax”.

I’m feeling like “Values” first, for the ‘scanners’, then “Formal Syntax” later, followed by " Syntax" (list of variations). But when either syntax subsection is a big fat wall, whichever is bigger last?

When I look at documentation that is off-putting it is often because the sheer size of a ‘sub-unit’ looks like a big splat’o’text between where I’ve been and what I want to find next in an article.

So, keep but relocate alongside “Formal Syntax”, but what guidance for importance within “Syntax” section?

1 Like