1459030 - Please move the JavaScript Demo lower on the page

Status: RESOLVED WONTFIX

(Developer Documentation Graveyard :: General, defect)

Description

[Ryan Patterson]

:: Developer Documentation Request

      Request Type: Correction
     Gecko Version: unspecified
 Technical Contact: 

:: Details

This is general feedback about the MDN website; I apologize if this is not the right channel; please point me in the right direction if so.

I'd like to request that the recently-added "JavaScript Demo" inserted at the top of every documentation page be moved lower down on the page. This widget has been assigned a higher priority than the "Syntax" section of the documentation, and pushes said section below the fold on my moderately large screen. The Syntax section is vastly more commonly referenced than the demo. Some specific examples:

- Array.prototype.splice - The demo shows me `months.splice(1, 0, 'Feb'); // inserts at 1st index position`, but the syntax section shows me `array.splice(start[, deleteCount[, item1[, item2[, ...]]]])`, which is much more useful and easier to parse due to the named variables.
- Array.prototype.reduce - The demo shows `const reducer = (accumulator, currentValue) => accumulator + currentValue;` which is good! But not as good as `arr.reduce(callback[, initialValue])`, followed by the documentation for `callback` showing all 4 arguments to the function.
- Date - The demo shows 2 specific usage examples, but the syntax section concisely shows all 10 ways you can actually invoke the function.

In conclusion, I've found that the utility of the MDN website has gone down as a result of the Demo section being placed above all other content on the page.

Comment 1

[Will Bamberg [:wbamberg]]

I'm sorry to be so slow to respond here. I tried to get some extra feedback for you, but that kind of stalled.

When designing this feature we thought about where best to put these examples. We know that different people want to use the docs in different ways, and in particular some want to go straight to an example, while some want the syntax.

Based on the user testing we did, we decided that most people want to go straight to an example, so we've optimized for that. I acknowledge that this is a regression for some people, and I'm sorry that you are in that group.

But, your feedback is definitely valuable: we're continuing to monitor feedback on the pages, and will reconsider if it starts to look like we have got this wrong.

Do you feel the same way about the examples we have for the CSS docs (e.g. https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow) and the HTML docs (e.g. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/range)?

Comment 2

[Ryan Patterson]

First of all, thanks for responding!

To respond to your question, on the CSS page I think this is a very clear example where the demo is less helpful than the syntax. I find "10px 5px 5px red" conveys much less information than "/* offset-x | offset-y | blur-radius | color */". However, I should point out that the Syntax section of this page actually includes an example, so if the Demo section included the comments it would be equally helpful. Here's what I'm suggesting: https://pasteboard.co/Hxekn1t.png

For the HTML docs, there isn't really a Syntax section in the same way, the "supported common attributes" list of links is really the closest analog. I don't mind the demo being at the top here.

I'm unsure that you can apply the same "fix" I suggested to CSS to the JS docs without just being redundant. Here's what that might have looked like:

- splice: https://pasteboard.co/Hxeny6j.png
- reduce: https://pasteboard.co/HxeoZYz.png

I feel this is redundant, but if having a "live demo" near the top is a priority this might be a good compromise.

Comment 3

[Janet Swisher]

I'm closing this as WONTFIX, though I reiterate that we value your feedback. This might be an area for per-user customization if we ever implement that.