Beginner friendly docs: the syntax notation for optional parameters

[Elchi3]

On 30.10.2016, 18:44:36, I wrote to dev-mdc
https://groups.google.com/g/mozilla.dev.mdc/c/eS12O5mAI-A/m/J1Qd-HajBgAJ

Hi all,

I've been trying to improve readability of our documentation for a few
Array pages [1] lately. Sites like w3schools provide very basic examples
and avoid complex text and notations to be able to offer quick lookup
and to especially serve beginners and hobby programmers.

I've modified the Array pages to start with simple usage example code.
We have talked about this for longer and at least for Array pages, there
are examples on top as a start now.

Another change seems to be more controversial, so I would like to
discuss it: There is a bracket notation for optional parameters in the
syntax box. It looks like this:

array.splice(start[, deleteCount[, item1[, item2[, ...]]]])

This is common practise in documentation, but not everyone (especially
non-coders) are able to make sense of this. We have seen many edits to
the syntax box where people incorrectly changed the square brackets or
removed them. Also "[]" is an array in JS, so a method like
arr.sort([compareFunction]) can look confusing.

I have changed the Array#slice page to instead list all of the possible
parameter combinations and to use 3 lines separate lines:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice
Also, the parameter section clearly indicates what is optional.

See also some Stackoverflow threads on this
http://stackoverflow.com/questions/17132014/documenting-for-optional-parameters-in-javascript
http://stackoverflow.com/questions/21654192/what-do-the-brackets-around-the-arguments-mean-when-reading-documentation-for-a
http://stackoverflow.com/questions/16744652/what-does-this-mean-in-documentation-square-bracket-followed-by-comma

Some answers there also include lists of all combinations that can be
used for a method.

So, what do you think? Should we start to rather list all combinations
instead of square bracket notation for optional parameters?

Thanks,
Florian

[1]
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array

--
Florian Scholz
Technical Writer
Mozilla Developer Network

Sadly, given MDN was a wiki, the square bracket notation is back on pages like slice and friends. Opening this issue to restart the discussion and advocating again for using multiple lines instead. This came up in #2176 where folks seem to be positive about this proposal, too.

[Rumyra]

🙏 I've been considering this too @Elchi3 as it seems to be repeatedly coming up in issues.

I like the multiple line solution.

Clarifying:

arr.method(requiredParam);
arr.method(requiredParam, opt1);
arr.method(requiredParam, opt1, opt2);

I'm assuming (and it's not at all common but) if you have two optional params where you use one and the other is required it would go something like:

arr.method(requiredParam);
arr.method(requiredParam, opt1, opt2);

[rachelandrew]

I'd agree with this as a solution. Expecting people to understand the square bracket notation is really just adding an extra layer of complexity for them to understand. In the CSS docs we have syntax (which is equivalent to this approach) and then formal syntax (which is useful if you know how to read specs). Can we do the same sort of thing here?

Example: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-area

[chrisdavidmills]

For what it's worth, I completely agree with this solution.

[Ryuno-Ki]

Okay, given we seem to be on the same page …
can we make Yari does this for us in bulk? Or would it require a manual tweak on those pages?

[hamishwillee]

My understanding of this proposal is that

1. globally (not just arrays) we move towards the syntax section having the options "spelled out".
2. an optional heading Formal syntax section can be added that still uses the brackets, if this is seen as useful.

Yes to "1".

I don't really like throwing away the more compact BNF syntax (because I personally find it useful) and the inconsistency of sometimes having it and sometimes not. Just an idea, but could we include it as well?

So Syntax section might look like this:

Array/slice

// Formal syntax (BNF)
arr.slice([start[, end]])

arr.slice(); // Note sure what this means
arr.slice(start);  //Slice from  start index (0 based) to end
arr.slice(start, end) //Return slice from start to end-1

CSS similarly - or at the end ...

/* Keyword values */
grid-area: auto;
grid-area: auto / auto;
grid-area: auto / auto / auto;
grid-area: auto / auto / auto / auto;

/* <custom-ident> values */
grid-area: some-grid-area;
grid-area: some-grid-area / another-grid-area;

/* <integer> && <custom-ident>? values */
grid-area:  4 some-grid-area;
grid-area:  4 some-grid-area / 2 another-grid-area;

/* span && [ <integer> || <custom-ident> ] values */
grid-area: span 3;
grid-area: span 3 / span some-grid-area;
grid-area: 2 span / another-grid-area span;

/* Global values */
grid-area: inherit;
grid-area: initial;
grid-area: unset;

/* Formal syntax (BNF) */
<grid-line> [ / <grid-line> ]{0,3}where <grid-line> = auto | <custom-ident> | [ <integer> && <custom-ident>? ] | [ span && [ <integer> || <custom-ident> ] ]

@rachelandrew FMI, in https://developer.mozilla.org/en-US/docs/Web/CSS/grid-area is it intentional that the syntax values refer to grid-area but the formal syntax refers to <grid-line>?

[chrisdavidmills]

I don't really like throwing away the more compact BNF syntax (because I personally find it useful) and the inconsistency of sometimes having it and sometimes not. Just an idea, but could we include it as well?

I don't really see the point of this. I think we should just stick to one way of doing it. We get so many bugs filed by people not understanding this syntax, and PRs filed to remove the brackets because people think they are a mistake...

[Ryuno-Ki]

arr.slice(); // Note sure what this means => copy the whole array (shallow)

[hamishwillee]

What's the general feeling on commenting the syntax itself or leaving that to the description (I decided to test this with #2351).

slice()        // Copy (shallow) whole array
slice(start)       // Slice from start index (0 based) to end of array
slice(start, end)  // Slice from start index to element before 'end' index (0 based)

OR

slice()
slice(start) 
slice(start, end)

I very slightly lean towards "no comments". I like the "at a glance" nature of having them, but then this does omit some detail from the docs that people might then not read.

[Elchi3]

I'm also leaning towards no comments. (Ideally this would be something to user test if we had the capacities like we used to 😞.)

In my view the syntax box is really just meant to lookup how to use the function if you need a reminder about the parameters. If you then see "start" and "end" and don't know what these are, well, then you need to go on reading the page, specifically the "Parameters" section. If you know about "start" and "end", well, then go back to your code editor as quickly as possible :)

[Ryuno-Ki]

No comments.
This increases the likelihood, that it will remain readable even on smaller viewports.

[hamishwillee]

OK, that all makes sense. I am thinking that perhaps we should still show the return type -ie
Array slice() rather than just slice(). Any opinion?

I've tried to capture this in #2376

[Elchi3]

I think it is an interesting idea to add return types. It adds essential information to the syntax box which wants to be a useful, quick look-up. However, if we do this, it should be as readable as possible. I looked at Python, Rust, PHP docs, and I guess there are a at least two different ways how people do this:

Add the return type in front (with or without colon, like you proposed).

Add the return type at the end (to represent what comes out of the call, I assume)

My feeling is that we start with making the change to multiple lines now and iterate on the syntax box in a second phase to add return types? I'd like to gather more feedback/experience with return type syntax first, before recommending something here. Does that make sense?

[Ryuno-Ki]

The second version would lean more towards TypeScript.

But if we start with using type annotations - should the arguments get annotated as well?
How likely is it that those will be copy-pasted? (I hope, very unlikely in this part of a page)

[chrisdavidmills]

I think it is an interesting idea to add return types

I agree that this is interesting. My main concern here is that it might confuse beginners more, as they might think that the return type is part of the syntax. Surely putting the return type in a separate section like we do already is a safer bet?

But yes, let's proceed with multiple lines now, and discuss this more later.

[Ryuno-Ki]

Since we agreed upon multiple-lines, I feel like another issue for type annotations might be apt.

[peterbe]

I personally prefer the multi-line format instead of the cryptic [brac [kets]].
I hope we can pull off a mass-edit quite quickly (not "soon" but at a high rate) so we don't leave some documentation in the old format.

Go get 'em folks!

[hamishwillee]

FWIW I would prefer to resolve whether we want type annotations in the syntax before we go forth and mass edit. Otherwise I fear we will end up with documentation with multiple formats.

... it might confuse beginners more, as they might think that the return type is part of the syntax.

This is not like confusing beginners by mixing BNF and legitimate programming language syntax. The return type and types of the arguments are part of the programming language syntax.

Many docs provide a full function signature, because that is what a programmer needs to understand how to use the API.
We can choose not to do this, but we need to understand that what we're providing is then not actually a syntax box.

IMO it doesn't matter too much though, as long as we make sure that we explicitly always list the return types and types of each of the arguments. I prefer types to be listed, because reading signatures is an important skill for beginners to learn (much faster and easier to grok an API than wading through docs). But it is a hell of a lot more work, and perhaps not all that relevant for languages like JavaScript that wouldn't know a type if it bit them on the face :-)

[hamishwillee]

Just to confirm, the intent is to also follow the same model for single lines too right? So

responseStr = element.querySelector(selector);

would become

querySelector(selector);

plus whatever we end up doing for type notation.

[SebastianZ]

@hamishwillee wrote:

@rachelandrew FMI, in https://developer.mozilla.org/en-US/docs/Web/CSS/grid-area is it intentional that the syntax values refer to grid-area but the formal syntax refers to <grid-line>?

The syntax values provide examples on how the CSS property is used, similar for the syntax examples at the top but for all different kinds of values. I.e. they include complete property declarations including the name and value.

The formal syntax, on the other hand, reflects the BNF-like syntax used in the specifications. It only defines the valid values and doesn't include the property name. In the case of grid-area the syntax is <grid-line> [ / <grid-line> ]{0,3}.

@chrisdavidmills wrote:

I don't really like throwing away the more compact BNF syntax (because I personally find it useful) and the inconsistency of sometimes having it and sometimes not. Just an idea, but could we include it as well?

I don't really see the point of this. I think we should just stick to one way of doing it. We get so many bugs filed by people not understanding this syntax, and PRs filed to remove the brackets because people think they are a mistake...

I'd personally be very sad if the formal syntax went away, less because I put a lot of effort into their generation and display back then (which obviously got broken by the switch to the new platform) but rather because it provides useful information on what values are allowed in a very compact way. And that information is not always reflected in the syntax values.

Though I can understand that this syntax can be quite confusing if you are not used to read it.

Regarding the issue about the display of optional parameters, I still prefer a condense display including square brackets. Like I wrote in the old discussion, it would then be good to have some kind of info icon near the syntax that explains its meaning.

But, like with the formal syntax in CSS, it might be easier for people not familiar with that special syntax if the different possible versions are listed like you did it in https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice#syntax.

Sebastian

[hamishwillee]

Hi @SebastianZ

The consensus of the discussion was that the BNF form is deprecated and we should use the expanded form "by default". Using BNF is allowed in a separate section. See https://developer.mozilla.org/en-US/docs/MDN/Structures/Syntax_sections

For myself I prefer the BNF format, but I have come around to the idea that this change is "for the better". The main reason being that we keep on getting people "correcting" the BNF in various ways. It isn't just that they confuse the brackets for array syntax, they confuse where the comma should be, and even that the brackets are some kind of odd emphasis. Now people rarely contribute, so if we have 6 changes in a month then we probably have 6000 people scratching their heads on what this means.

Given that the BNF is still "allowed" an icon or something to link to an explanation would not hurt, but given it isn't the preferred way, not sure it is "a priority". Just my opinion though.

PS
The format also changed for the single lines to match.

I will close this discussion next time I come around to this, because I think it completed and further discussions on the topic - e.g. to somehow revert this, should be separate.

[SebastianZ]

Hi @hamishwillee,

Right, the expanded form is the preferred way to present the syntax as it is easier to understand.

It's bad that contributors try to "correct" the formal syntax as they misinterpret it. That's why I wanted to have that info icon. Before Yari, the parts of the formal syntax were actually linked to https://developer.mozilla.org/en-US/docs/Web/CSS/Value_definition_syntax, which made it somewhat easier to understand.

And users will have to understand the formal syntax to some extent when they want to define custom properties via the CSS Properties and Values API.

Anyway, the discussion is far beyond @Elchi3's initial intent to clarify the syntax notation for optional parameters in JS, at this point. So I'll open a separate issue to discuss that.

Sebastian

[SebastianZ]

Before Yari, the parts of the formal syntax were actually linked to https://developer.mozilla.org/en-US/docs/Web/CSS/Value_definition_syntax, which made it somewhat easier to understand.

Just saw that there's already mdn/yari#2963 to fix that.

Sebastian

[hamishwillee]

And users will have to understand the formal syntax to some extent when they want to define custom properties via the CSS Properties and Values API.

@SebastianZ I'd have to see some examples of that to understand why the formal syntax is required rather than expanded format for the CSS case you point to. I'm completely open to the discussion, just need an agreed set of rules I can work to.

Closing this issue.

[Elchi3]

I'm closing this issue. We've agreed on new guidelines and updated the MDN contribution docs.
Further, I've updated all JavaScript pages to use the improved and more beginner friendly syntax blocks.
For the API/ page tree, updates to syntaxes can happen as we see them. New pages should use this new convention.

Thanks all! 🎉

[hamishwillee]

Amazing job @Elchi3. I love consistency. Now we just need to get someone to do the web api docs ....