CSS: consider reuniting "Formal syntax" and "Values"

[wbamberg]

In the old days, on CSS pages, the formal syntax section came before the "Values" section, inside "Syntax":

• 2014: https://web.archive.org/web/20140305011542/https://developer.mozilla.org/en-US/docs/Web/CSS/border#Syntax

The "Values" section described items listed in the formal syntax.

Because formal syntax was hard to read, we decided to move it further down the page in favour of more informal descriptions, first into a section just after "Values":

• 2020: https://web.archive.org/web/20200319022331/https://developer.mozilla.org/en-US/docs/Web/CSS/border#Syntax

...then eventually to its own top-level section, miles away from "Values":

• 2021: https://web.archive.org/web/20210413221123/https://developer.mozilla.org/en-US/docs/Web/CSS/border#formal_syntax

This causes coherency problems in our pages: the "Values" section still refers to things that are introduced in the formal syntax (e.g. <line-width> in the example above). In fact these two sections are quite closely linked.

I wonder if, now the formal syntax is easier to read, we should move it back before the "Values" section, so these two sections can work better again.

[wbamberg]

@dipikabh asked whether there was history about the names of the sections, since our current "Syntax" block is not really syntax definition as all, but more like examples of the syntax.

IIRC originally there was only what we now call "Formal syntax", and it was called just "Syntax": https://web.archive.org/web/20140305011542/https://developer.mozilla.org/en-US/docs/Web/CSS/border#Syntax. We wanted to have a more approachable/readable way to show the syntax, and added these sections giving example syntax. Then we needed a new name for the original syntax, so it got the name "formal syntax": https://web.archive.org/web/20180530112352/https://developer.mozilla.org/en-US/docs/Web/CSS/border#Syntax.

I still like the "example syntax" and think that probably for most people most of the time it's more likely to be useful than the formal syntax.

I think now we could perhaps have something like:

## Syntax

// syntax example

### Syntax definition (/Formal syntax)

// formal syntax

### Values

// values dl

[dipikabh]

Porting the slack discussion here for everybody's eyes and opinions:

@dipikabh:

• 'Syntax' should probably be called 'Syntax usage' (or another variation?) because we list examples in this section using the possible syntax options and not the real syntax.
• Is there a reason why 'Formal definition' is before 'Formal syntax'?
• I agree 'Values' should come after FS. Another point to consider is if 'Values' should be an H2 or H3.
• So could the section order be: Try It - Constituent properties (if applicable) - Description (if there is more to say than the intro para) - Syntax usage - FD - FS - Values - Examples - Spec - BCD - See also

@teoli2003:

• Syntax usage. What about Usage?
• I think we put FS after Examples because people are using Examples more. And being at the bottom of the page (because Spec/BCD/See also are usually sort) still allows interested people to find it quickly.
• If we put FS up again, maybe we can hide it by default like in a <summary> /<details> combo. That way, it doesn't push examples so far away and is still one click away for people interested.
• There was a lot of user research about this back then. It may be interesting to conduct user interviews again..

@wbamberg:

• FS is not after examples. And hiding it in <details> still creates the problem that "Values" does not make sense unless people expand it.

Try It - Constituent properties (if applicable) - Description (if there is more to say than the intro para) - Syntax usage - FD - FS - Values - Examples - Spec - BCD - See also

I would like to consider grouping "syntax usage", "fs", "values" under an H2, to emphasise the fact that they are part of the same aspect of the documentation (and distinct from say BCD or Specs). And I'm not sure "Syntax usage" needs a heading. Also I think mockups help with this 🙂

[dipikabh]

@wbamberg I like the idea of grouping "FS", "Values", "Usage". "FS" an H2 and "Values" and "Usage" H3s under it. I would retain the "Usage" heading just to have a pointer to access that section quickly. So a slightly different version from what Will has proposed above:

## Formal syntax
// formal syntax

### Values
// values dl

### Usage
// syntax example

• Where does FD fit in the scheme of things?
• I have seen "Description" in different places. I feel it should be right after "Try it".

[wbamberg]

• Where does FD fit in the scheme of things?

Good question. I don't know yet :). I think when we get to webref-ify this, we might have a better idea.

• I have seen "Description" in different places. I feel it should be right after "Try it".

It's fairly conventional in our docs for this to live after "Syntax", e.g.:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize

I like this for a couple of reasons:

• I think people are more likely to want to know syntax when they look up information in the reference, but are less likely to want to wade through the words (of course this is a user testing question). IME people only read words as a last resort.
• We sometimes have more prose sections for things like "Accessibility concerns" and it seems nice to glom all the prose-y things together.

(A meta-question here is whether we should do user testing to resolve all page structure questions in this thread, and whether we should block the specific change here (reuniting FS and Values) on that.)

## Formal syntax
// formal syntax

### Values
// values dl

### Usage
// syntax example

I'd be OK with this, but would call it just "Syntax". And I still prefer having the syntax examples first, because I think it is more often of use to more people. (I use the formal syntax when I have to.)

[Rumyra]

I think we put FS after Examples because people are using Examples more. And being at the bottom of the page (because Spec/BCD/See also are usually sort) still allows interested people to find it quickly.

I think this is an important point, I did a litmus test when we started considering webref for formal syntax instead of data. Most of the feedback was the same when asked whether users take note of the the formal syntax sections, like:

"Hardly ever! Can be pretty baffling on some longer entries."
"Can't say I ever noticed it"

That's not to say I'm against moving it as I think categorically it does fit better within the syntax and values parts. But maybe we should consider which parts of a CSS reference page are the most useful for our users (I assume this is why the original change was made)

[wbamberg]

I think we put FS after Examples because people are using Examples more. And being at the bottom of the page (because Spec/BCD/See also are usually sort) still allows interested people to find it quickly.

I think this is an important point, I did a litmus test when we started considering webref for formal syntax instead of data. Most of the feedback was the same when asked whether users take note of the the formal syntax sections, like:

"Hardly ever! Can be pretty baffling on some longer entries." "Can't say I ever noticed it"

That's not to say I'm against moving it as I think categorically it does fit better within the syntax and values parts. But maybe we should consider which parts of a CSS reference page are the most useful for our users (I assume this is why the original change was made)

Yes, people do say that. I hope it might be less baffling now, but it's never going to be easy, especially in more complicated cases.

What I don't get, though, is that the "Values" section does not make sense without the FS. For example, https://developer.mozilla.org/en-US/docs/Web/CSS/border#values - what is <line-width> supposed to be, here? So either people are somehow understanding this anyway(?), or they are not understanding this either, and they're just relying on copying the syntax-by-example bit or the interactive example.

But if the latter, then our pages aren't effectively describing the syntax of properties at all.

Perhaps we could do some more in-depth user testing to see how people do actually use these pages.

[rubiesonthesky]

What I don't get, though, is that the "Values" section does not make sense without the FS. For example, https://developer.mozilla.org/en-US/docs/Web/CSS/border#values - what is <line-width> supposed to be, here? So either people are somehow understanding this anyway(?), or they are not understanding this either, and they're just relying on copying the syntax-by-example bit or the interactive example

I think some users already know some CSS and / or these these terms and can understand that these are referring the examples.

I think for this page, it's little bit confusing to have consistuent properties and values so far apart.

Reading formal syntax or formal definition feels like chore. They are not easy to skim through, especially in mobile. I think just making font size a little bit smaller in formal syntax would help, as it would then fit better on screen. If i need to scroll to see whole syntax (as is the case for border), I'm going to refer some other source.

This is just one user's perspective for this. There may not be one easy and simple answer for this question.

[dipikabh]

Based on the sections that are most helpful to readers, how about the order somewhat along the lines of what's described here. This proposal does not take into account if there'll be any implementation hiccups (in content or platform), just throwing ideas out there. Also, not sure if this will be extendable to JS docs.

• In the "Usage" section (proposed new name for the "Syntax section" but no consensus yet), we can state the syntax in a comment before we add a usage sample. This would solve the problem that "Values" section uses parameter names that are only referred to later in the "Formal syntax" section.
• We can also try to limit the length of the "Usage" section to show only a sample of each kind.
• Should "Values" be called "Parameters" or "Options" instead? I am suggesting below to turn it into an H2.
• How about moving FS and FD under "Specifications" because that's where they are coming from? Also, how about making FS and FD collapsible so that readers expand the sections only if they need to but the information is there.

Using https://developer.mozilla.org/en-US/docs/Web/CSS/animation-delay#syntax as an example here.

## Try it
// interactive example

## Usage
/* For a single animation */
/* animation-delay: <time>; */
animation-delay: 3s;
animation-delay: -1500ms;

/* For multiple animations */
/* animation-delay: <time>, <time>; */
animation-delay: 2.1s, 480ms;

## Parameters
// dl

## Description

## Examples

## Specifications
// url table
### Formal syntax
### Formal definition

## Browser compatibility

## See also

Consider another page https://developer.mozilla.org/en-US/docs/Web/CSS/border-style#syntax.

• The "Syntax" section should not list all the possible values; that should be done in the "Values" section.
• Perhaps even the list of all applicable "Global values" should be moved out of "Syntax" and mentioned in the "Values" section.

## Try it
// interactive example

## Constituent properties

## Usage
/* 1 value applies to all sides */
/* border-style: <line-style>; */ 
border-style: dotted;

/* 3 values apply to top | left and right | bottom */
/* border-style: <line-style> <line-style> <line-style>; */ 
border-style: hidden double dashed;

...

## Parameters
// dl
// also mention the global values that this property can be assigned

## Description

## Examples

## Specifications
// url table
### Formal syntax
### Formal definition

## Browser compatibility

## See also

[teoli2003]

I think it is important for coherence that items in "Values" have the same names as items in formal syntax.

Do we have a way to detect when a formal syntax in webref changed? (This happens from time to time) because we need to update the page on MDN.

[wbamberg]

I think it is important for coherence that items in "Values" have the same names as items in formal syntax.

Do we have a way to detect when a formal syntax in webref changed? (This happens from time to time) because we need to update the page on MDN.

No. But I'm not sure that's really different from any other way we don't get notifications when the spec changes in ways that should trigger MDN updates.

[teoli2003]

It is fairly different. A formal syntax change can make a page incoherent, while another change, it can make the change outdated, and only if a browser implements the change.

[dipikabh]

I think we should do what's right for the page structure now, and hope the ToC catches up soon (do you know where that work is/whether something is blocking it?)

A discussion is open and the engineering team is aware of it. I am not aware of the implementation timeline.

Maybe I should start a PR with a few pages in, so we have something concrete to work on?

Sounds good!

[Rumyra]

@dipikabh I suggest you raise an issue on yari to expose the h3s in TOC - I think we're mainly in consensus this is a good thing - we shouldn't block making sure page structures are there first, because the opposite is also true, we wait for page structures before doing it - but either or are going to influence moving forward

[yarusome]

The crucial point here is that different reader groups have different expectations for the "Syntax" section. There're at least two groups:

1. beginner- to intermediate-level devs that try to grasp the basic ideas from this section;
2. experienced devs that look up this section for assurance and details.

Some threads here are focusing on a single group, but it's better to accommodate both.

Another issue I found during the work on CSS Color Module is that the current structure makes it awkward to explain functional notations, e.g. starting the "Values" section with a note on the syntax as on the hsl() page.

Therefore, I think the proposed structures could be further tweaked like this:

## Syntax

[{Optional} Intuitive rephrasing of the syntax here][1]

[Current "Formal syntax" here][2]

### Values

### "Examples" (<- A bad name for a placeholder, current "Syntax" here)

## Definition

[Current "Formal definition" here]

[1] serves Group 1 and functionnal notations, and [2] serves Group 2. However, there're some caveats:

1. There should be a clear distinction between [1] and [2] - either a phrasing or a visual one - so that readers won't be confused as "Why there're two different syntaxes?".
2. As already mentioned in other threads, the current implementation of {{CSSSyntax}} sometimes makes really lengthy expansions, e.g. display and transition-timing-function, which make readers lost in details. (Btw, this macro has been needing updating for quite some time, see chore(deps): bump @webref/css from 5.4.4 to 6.5.7 yari#8909.)

The culprits for Point 2 are:

• The macro doesn't stop at data types already exist on MDN, which is due to the ad hoc logic on Line 16 to 17.
• The format is rather spatially uneconomical. For example, the syntax of <display-internal> could use flexbox or display: inline-block (see CSS Text) to save space and align the items at the same time.

In case the formal syntax is still too lengthy after the above optimizations, a last resort is to set max-height on this part.

---

Incidentally, I'm working on an automation script to diff mdn/data and webref so that future updates to mdn/data could be much easier.

---

A demo with white-space: pre-wrap + display: inline-block for <display-internal>:

Code:

<pre class="notranslate" style="white-space: pre-wrap;"><span class="token property" id="<display-internal>">&lt;display-internal&gt; = </span><br><span style="display: inline-block;">  <span class="token keyword">table-row-group</span>      <a href="/en-US/docs/Web/CSS/Value_definition_syntax#single_bar" title="Single bar: exactly one of the entities must be present">|</a></span><span style="display: inline-block;">  <span class="token keyword">table-header-group</span>   <a href="/en-US/docs/Web/CSS/Value_definition_syntax#single_bar" title="Single bar: exactly one of the entities must be present">|</a></span><span style="display: inline-block;">  <span class="token keyword">table-footer-group</span>   <a href="/en-US/docs/Web/CSS/Value_definition_syntax#single_bar" title="Single bar: exactly one of the entities must be present">|</a></span><span style="display: inline-block;">  <span class="token keyword">table-row</span>            <a href="/en-US/docs/Web/CSS/Value_definition_syntax#single_bar" title="Single bar: exactly one of the entities must be present">|</a></span><span style="display: inline-block;">  <span class="token keyword">table-cell</span>           <a href="/en-US/docs/Web/CSS/Value_definition_syntax#single_bar" title="Single bar: exactly one of the entities must be present">|</a></span><span style="display: inline-block;">  <span class="token keyword">table-column-group</span>   <a href="/en-US/docs/Web/CSS/Value_definition_syntax#single_bar" title="Single bar: exactly one of the entities must be present">|</a></span><span style="display: inline-block;">  <span class="token keyword">table-column</span>         <a href="/en-US/docs/Web/CSS/Value_definition_syntax#single_bar" title="Single bar: exactly one of the entities must be present">|</a></span><span style="display: inline-block;">  <span class="token keyword">table-caption</span>        <a href="/en-US/docs/Web/CSS/Value_definition_syntax#single_bar" title="Single bar: exactly one of the entities must be present">|</a></span><span style="display: inline-block;">  <span class="token keyword">ruby-base</span>            <a href="/en-US/docs/Web/CSS/Value_definition_syntax#single_bar" title="Single bar: exactly one of the entities must be present">|</a></span><span style="display: inline-block;">  <span class="token keyword">ruby-text</span>            <a href="/en-US/docs/Web/CSS/Value_definition_syntax#single_bar" title="Single bar: exactly one of the entities must be present">|</a></span><span style="display: inline-block;">  <span class="token keyword">ruby-base-container</span>  <a href="/en-US/docs/Web/CSS/Value_definition_syntax#single_bar" title="Single bar: exactly one of the entities must be present">|</a></span><span style="display: inline-block;">  <span class="token keyword">ruby-text-container</span>  </span><br></pre>

Given the above format, if extra-long items are allowed to occupy more than one column, there arises an interesting math problem to decide the most economical column width.

[wbamberg]

The macro doesn't stop at data types already exist on MDN, which is due to the ad hoc logic on Line 16 to 17.

Indeed. But this was a deliberate choice, because making all the syntaxes stop when there is the possibility of linking to another page makes the formal syntax very fragmentary, so people would have to navigate to lots of pages in order to get a sense of what's possible for a given property. display is a good example of that actually: yes it is long(ish), but if it delegated to all the types it would be very hard to get a sense of what the possible concrete values are.

The ad hoc treatment of <gradient> and <color> are because expanding those types really does make the syntax huge, and they end up in many syntaxes.

The format is rather spatially uneconomical. For example, the syntax of could use flexbox or display: inline-block (see CSS Text) to save space and align the items at the same time.

I think this is a tradeoff: you save vertical space, but IMO it's much easier to scan a 1-column list than multiple columns. 🤷 .