Beginner friendly docs: the syntax notation for optional parameters

[Florian Scholz]

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

[Sebastian Zartner]

I just want to remind that we already had a discussion previously about this. See https://groups.google.com/d/topic/mozilla.dev.mdc/ucaUxwA2xIQ/discussion.

Personally, I'm tending to keep the square brackets but add some '?' badge referring to a syntax definition page like it's done in the CSS area. This also keeps the API definitions somewhat consistent with the ones in CSS (even when they are not completely equivalent).

Though my opinion about this is not very strong, so it would be ok for me if we removed the square brackets. And I like the way you did it for Array#slice. Though that way may become complex when there are several optional parameters.

Sebastian

[Chris Mills]

I am all in favour of having it done like Florian’s Array.slice example. Confusion over the formal syntax comes up so often as a problem beginners have with our documentation.

Of course, ideally it would be nice for us to include both somehow, so beginners can see something they understand, but advanced folk can also just grab the formal syntax and run with it, plus beginners can also have a chance to learn what the formal syntax is.

Something like

h2 Syntax

h3 Formal syntax

include the formal syntax under here, along with a question mark badge referring to the syntax definition page.

h3 Syntax examples

include different syntax examples, like on Florian’s page

h3 Parameters

etc.

But I guess this would be too complex.


What about showing the Syntax examples by default, but providing a user preference to show Formal syntax instead (or as well?)

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

> On 31 Oct 2016, at 08:20, Sebastian Zartner <sebastia...@gmail.com> wrote:
>
> I just want to remind that we already had a discussion previously about this. See https://groups.google.com/d/topic/mozilla.dev.mdc/ucaUxwA2xIQ/discussion.
>
> Personally, I'm tending to keep the square brackets but add some '?' badge referring to a syntax definition page like it's done in the CSS area. This also keeps the API definitions somewhat consistent with the ones in CSS (even when they are not completely equivalent).
>
> Though my opinion about this is not very strong, so it would be ok for me if we removed the square brackets. And I like the way you did it for Array#slice. Though that way may become complex when there are several optional parameters.
>
> Sebastian
>
>
> On Sunday, October 30, 2016 at 6:44:36 PM UTC+1, Florian Scholz wrote:

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide

[Joe Medley]

Florian,

I really like your informal approach to syntax. I like it enough that I'd be happy to help rewrite syntax sections across the site and write instructions how do do them properly.

But, I'm not crazy about putting an example in the introduction. Though I agree with the intent of putting something up front, I think it's going to be hard to enforce keeping it simple. I'm not just thinking of writers who may not respect the restriction or who think philosophically that every nuance has to be covered up front. Many cutting edge APIs require more context for their examples than do basic JavaScript features. That also means more explanation and the possibility that the intro becomes bloated to the point that it's no longer effectively an introduction. (Yes, I just made a slippery slope argument. Those are easy to assert and difficult to prove. But I rarely make them, and when I make them I don't do it lightly.)

Joe

[Florian Scholz]

Thanks Joe!

Answers inline.

Am 31.10.2016 um 18:40 schrieb Joe Medley:
> Florian,
>
> I really like your informal approach to syntax. I like it enough that I'd be happy to help rewrite syntax sections across the site and write instructions how do do them properly.

This sounds great! Having instructions on how to write the syntax
section might help this discussion (which I started twice already.
Thanks Sebastian, I completely forgot it).

> But, I'm not crazy about putting an example in the introduction. Though I agree with the intent of putting something up front, I think it's going to be hard to enforce keeping it simple. I'm not just thinking of writers who may not respect the restriction or who think philosophically that every nuance has to be covered up front. Many cutting edge APIs require more context for their examples than do basic JavaScript features. That also means more explanation and the possibility that the intro becomes bloated to the point that it's no longer effectively an introduction. (Yes, I just made a slippery slope argument. Those are easy to assert and difficult to prove. But I rarely make them, and when I make them I don't do it lightly.)

I think there is no general approach to examples in the introduction.
MDN is not using auto-generated API documentation, so we are able to
make judgements on a case by case basis.

For many ECMAScript methods, a lot can be explained in 5 lines of code,
and often that is all you want and people go to w3schools just to copy &
paste code that uses Array#slice, because they don't memorize how to use
it. For the Array pages, I've added the simplest case of using a method
and have left out any more complicated use in the intro. More advanced
code that uses all parameters etc should go in the example section more
below on the page. I completely agree that the intro shouldn't be
bloated, so the goal is indeed to be very short and concise. The only
exception here is the Array main object page itself, where multiple
small usage examples are presented. I also think that this makes sense,
but I am eager to hear more opinions.

Our docs try to serve example-driven and concept-driven programmers, we
believe that we have served more concept-driven programmers in the past.
By being more focused on the examples (and having them presented first),
I hope to help example-driven programmers faster (Stackoverflow has
shown that there are a lot of them).

Florian.

[Joe Medley]

On Mon, Oct 31, 2016 at 11:06 AM, Florian Scholz <fsc...@mozilla.com>
wrote:

> More advanced code that uses all parameters etc should go in the example
> section more below on the page.

I understand where you're coming from and what the goal is. The general
theme of my comment, which I should have made clearer, was how are you
going to enforce it? It's my impression that the people who add consistency
to MDN are outnumbered by people create inconsistencies. (That's inherent
in the nature of wikis. I hope I haven't insulted any contributors here.)

Joe Medley | Technical Writer, Chrome DevRel | jme...@google.com |
816-678-7195
*If an API's not documented it doesn't exist.*

[Jeremie Patonnier]

Hi Florian!

For what it worth, I really like what you did with the Array#slice page, it
makes things very easy to understand and straightforward. I strongly
support any initiatives that will lead to make this a general solution for
MDN reference pages.

Best,
Jeremie

> Florian Scholz
> Technical Writer
> Mozilla Developer Network
>

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide
>

--
Jeremie
.............................
Web : http://jeremie.patonnier.net
Twitter : @JeremiePat <http://twitter.com/JeremiePat>