Syntax notation for optional parameters

[Florian Scholz]

Hi,

it has been brought up several times that syntax boxes containing a
notation for optional parameters is confusing to beginners.

Example:

str.split([separator[, limit]])


Should we, in general, just put the "optional" inline banner next to the
parameter descriptions and leave out the additional brackets in the
syntax box?

-Florian

--
Florian Scholz
Technical Writer
Mozilla Developer Network

[Chris Mills]

I wholehearted agree with this.

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide
> Doc project Trello board: https://trello.com/b/HAhl54zz/status

[Sebastian Zartner]

I thought this is commonly known as syntax for API definitions. For
example PHP also uses it in its documentation.
It's ok for me to remove the square brackets, but could we mark the
parameters differently, somehow, to keep it obvious within the
definition?

Sebastian

[Saurabh Nair]

These brackets confused me a lot in the early days. But once you get the
hang of it, it's quite useful (similar to the CSS value definition syntax).
While I very much like any change that makes MDN more beginner friendly, I
don't feel strongly for abandoning standard notations.

What comes as a compromise to my mind is using a "(?)" icon or such which
when hovered over shows the elaborated beginner friendly version in a
tooltip. But I know hovers and tooltips aren't really mobile friendly.

My vote is to have both, _somehow_ :)

On Wed, Jul 6, 2016, 5:43 PM Sebastian Zartner <sebastia...@gmail.com>
wrote:

[William Bamberg]

This sounds like the sort of thing we could test :).

[Eric Shepherd]

The brackets are a standard notation that have been used for decades in
documentation I've read going back to the mid-1980s. I would rather see
us have some information available in our meta docs to explain to
readers how to understand them, rather than change to add a bunch of
badges into the middle of syntax definitions.

While I agree that "just because that's how it's always been done" isn't
always the right answer, I think this may be a scenario where tinkering
with it will cause more problems than it solves. If we've only gotten a
few queries on this (I've never heard any at all in a decade working on
MDN), that seems like a very questionable reason to make a change after
doing it the way we've done things for so long, with so few complaints
on the syntax.

I could, though, see having a little (?) icon in the corner of syntax
boxes that could be clicked to pop up an explanation of how to read the
syntax descriptions, to cover the cases where people are confused.

> I thought this is commonly known as syntax for API definitions. For
> example PHP also uses it in its documentation.
> It's ok for me to remove the square brackets, but could we mark the
> parameters differently, somehow, to keep it obvious within the
> definition?

--

Eric Shepherd
Senior Technical Writer
Mozilla Developer Network <https://developer.mozilla.org/>
Blog: https://www.bitstampede.com/
Twitter: http://twitter.com/sheppy
Doodle: http://doodle.com/the.sheppy

[Sebastian Zartner]

Actually, I am very much in favor of Sheppy's solution.

On 7 July 2016 at 13:50, Eric Shepherd <eshe...@mozilla.com> wrote:
> The brackets are a standard notation that have been used for decades in
> documentation I've read going back to the mid-1980s. I would rather see us
> have some information available in our meta docs to explain to readers how
> to understand them, rather than change to add a bunch of badges into the
> middle of syntax definitions.

As I understand Florian, he'd only like to remove the square brackets
from the syntax. He meant to add the badges besides the parameter
descriptions, what is already the case now, so there's nothing to
change in this regard.

> While I agree that "just because that's how it's always been done" isn't
> always the right answer, I think this may be a scenario where tinkering with
> it will cause more problems than it solves. If we've only gotten a few
> queries on this (I've never heard any at all in a decade working on MDN),
> that seems like a very questionable reason to make a change after doing it
> the way we've done things for so long, with so few complaints on the syntax.
>
> I could, though, see having a little (?) icon in the corner of syntax boxes
> that could be clicked to pop up an explanation of how to read the syntax
> descriptions, to cover the cases where people are confused.

Note that this is also what we're already doing (on hover) for CSS syntax boxes.

Sebastian

[Chris Mills]

Adding some explanation on how to read this syntax would be helpful, yes. I still think we should do away with the brackets, but I think I may be outvoted here ;-)

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills