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:
-
it’s not constrained to 6 options, so for more complex syntaxes it can show more variations.
-
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:
-
should we just scrap this block?
-
should we keep it?
-
should we keep it for some pages, and not others?