Conventions about live samples?

[Sphinx]

Hello all,

While going over the CSS section for localization, I encountered several
styles for "live samples" and I'd like to be consistent across the fr
documents.

I propose the following:
1. Order of blocks:
- having the first block with the main language for this sample
(e.g. if this belongs to the CSS Ref, the CSS block should come first),
if there is no such "main" language, preferred order would be HTML then
CSS then JavaScript (SVG or MathML might come after HTML as content).

2. Having a "Result" block before {{EmbedLiveSample}}
- Currently, some samples have a "Result" heading before the macro,
some others have a "Output" heading, some others have a "Live Sample"
but most of them don't have anything that separates the result from the
code which is semantically weird.

3. Headings nomenclature
- If under "Examples" (most of the cases), headings texts' should
be "HTML","CSS","JavaScript" only. This would make things easier for
consistency, l10n and so on.

Actions regarding these:
A. filing bug 1246684 :
https://bugzilla.mozilla.org/show_bug.cgi?id=1246684 (done)
B. update
https://developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Live_samples
(in progress)
C. update
https://developer.mozilla.org/en-US/docs/MDN/Contribute/Guidelines/Code_samples
if necessary (TBD)


I know this might sound like nitpicking but I'd be glad to be consistent :)
Do you have any opinion on that matter?

As usual, feedback is welcome!

Respectfully,
Julien

[Jeremie Patonnier]

Sounds like a good plan for me (but I do less content than the others in
here :P)

++
Jeremie

> _______________________________________________
> 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
>



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

[Sebastian Zartner]

On 8 February 2016 at 18:38, Sphinx <sphinx...@hotmail.fr> wrote:

> Hello all,
>
> While going over the CSS section for localization, I encountered several
> styles for "live samples" and I'd like to be consistent across the fr
> documents.
>
> I propose the following:
> 1. Order of blocks:
> - having the first block with the main language for this sample
> (e.g. if this belongs to the CSS Ref, the CSS block should come first), if
> there is no such "main" language, preferred order would be HTML then CSS
> then JavaScript (SVG or MathML might come after HTML as content).
>

So far, I always used the order HTML, CSS, JavaScript. While I agree it may
make sense to have the code of the main language come first, I don't have a
strong opinion either way. Though I agree that we should decide on one way.

2. Having a "Result" block before {{EmbedLiveSample}}
> - Currently, some samples have a "Result" heading before the macro,
> some others have a "Output" heading, some others have a "Live Sample" but
> most of them don't have anything that separates the result from the code
> which is semantically weird.
>

Strongly agree on that there should always be a heading and that it should
be uniformly named across pages. Whether that's 'Result', 'Output' or 'Live
sample' still needs to be decided. My vote would be for 'Output', though
again without strong feeling about that.

> 3. Headings nomenclature
> - If under "Examples" (most of the cases), headings texts' should be
> "HTML","CSS","JavaScript" only. This would make things easier for
> consistency, l10n and so on.
>

I also agree on that. Note that if there are multiple examples, each
example should still have a heading by itself, but under that heading it
has only 'HTML', 'CSS' and 'JavaScript' as subheading.

One additional point:
If there's only one example, should it still be named 'Examples' with
plural 's'? I'd say no.

Sebastian

[duncan mcdonald]

>
> One additional point:
> If there's only one example, should it still be named 'Examples' with
> plural 's'? I'd say no.
>

Strongly agree with that point. Let's be grammatical, eh?

Duncan

[Stephanie Hobson]

Once you agree on a title for the result/output someone should open a bug
and assign it to me and I'll update the macro to output it :)

S.

On Mon, Feb 8, 2016 at 11:05 PM, duncan mcdonald <dmcdon...@gmail.com>
wrote:

>
> >
> > One additional point:
> > If there's only one example, should it still be named 'Examples' with
> > plural 's'? I'd say no.
> >
>

> Strongly agree with that point. Let's be grammatical, eh?
>
> Duncan
>

[Sphinx]

I've created this poll to choose the title: http://strawpoll.me/6878569/
If you have other ideas, please comment.

I suggest we wait a week or so before taking this poll into account.
As suggested, I'll update the bug.

Respectfully,
Julien

Le 10/02/2016 18:33, Stephanie Hobson a écrit :
> Once you agree on a title for the result/output someone should open a bug
> and assign it to me and I'll update the macro to output it :)
>
> S.
>
> On Mon, Feb 8, 2016 at 11:05 PM, duncan mcdonald <dmcdon...@gmail.com>
> wrote:
>

>>> One additional point:
>>> If there's only one example, should it still be named 'Examples' with
>>> plural 's'? I'd say no.
>>>

[Sphinx]

It turns out that it's a perfect draw between 3 answers :) (the last one
being "Other")

May someone cast a decisive vote so that I can comment on the bug with
his/her choice ;) ?

Thanks!
Respectfully,
Julien

Le 21/02/2016 10:09, Sphinx a écrit :
> I've created this poll to choose the title: http://strawpoll.me/6878569/
> If you have other ideas, please comment.
>
> I suggest we wait a week or so before taking this poll into account.
> As suggested, I'll update the bug.
>
> Respectfully,
> Julien
>
> Le 10/02/2016 18:33, Stephanie Hobson a écrit :
>> Once you agree on a title for the result/output someone should open a
>> bug
>> and assign it to me and I'll update the macro to output it :)
>>
>> S.
>>
>> On Mon, Feb 8, 2016 at 11:05 PM, duncan mcdonald
>> <dmcdon...@gmail.com>
>> wrote:
>>

>>>> One additional point:
>>>> If there's only one example, should it still be named 'Examples' with
>>>> plural 's'? I'd say no.
>>>>

[Stephanie Hobson]

I'm going to create a survey to circulate to my Twitter followers, I'll
share it here if anyone else wants to share it. (I want a new one because
I'll include an image to illustrate the problem for people unfamiliar with
MDN)

I'm going to swap "Live Sample" for just "Sample" in the new survey though
since "Live" suggests the user could interact with it.

S.

PS- Yes this is more thought than we should probably be putting into this,
but we do have to live with the, er, result, for a long time.

On Tue, Mar 8, 2016 at 12:06 PM, Sphinx <sphinx...@hotmail.fr> wrote:

> It turns out that it's a perfect draw between 3 answers :) (the last one
> being "Other")
>
> May someone cast a decisive vote so that I can comment on the bug with
> his/her choice ;) ?
>
> Thanks!
> Respectfully,
> Julien
>
>
> Le 21/02/2016 10:09, Sphinx a écrit :
>
>> I've created this poll to choose the title: http://strawpoll.me/6878569/
>> If you have other ideas, please comment.
>>
>> I suggest we wait a week or so before taking this poll into account.
>> As suggested, I'll update the bug.
>>
>> Respectfully,
>> Julien
>>
>> Le 10/02/2016 18:33, Stephanie Hobson a écrit :
>>
>>> Once you agree on a title for the result/output someone should open a bug
>>> and assign it to me and I'll update the macro to output it :)
>>>
>>> S.
>>>
>>> On Mon, Feb 8, 2016 at 11:05 PM, duncan mcdonald <dmcdon...@gmail.com
>>> >
>>> wrote:
>>>

>>> One additional point:
>>>>> If there's only one example, should it still be named 'Examples' with
>>>>> plural 's'? I'd say no.
>>>>>

[Stephanie Hobson]

Here's the survey:
https://www.surveygizmo.com/s3/2641342/3390c8e0f8ba

Feel free to take it again yourself too ;)
S.


On Tue, Mar 8, 2016 at 12:59 PM, Stephanie Hobson <sho...@mozilla.com>
wrote:

>>>> One additional point:
>>>>>> If there's only one example, should it still be named 'Examples' with
>>>>>> plural 's'? I'd say no.
>>>>>>

[Stephanie Hobson]

The winner of my in formal survey was "Result" at 13/21 responses.

This matches what both JS Fiddle and CodePen label their results panels so
I think it's a good conclusion.

S.

On Wed, Mar 9, 2016 at 10:58 AM, Stephanie Hobson <sho...@mozilla.com>
wrote:

>>>>> One additional point:
>>>>>>> If there's only one example, should it still be named 'Examples' with
>>>>>>> plural 's'? I'd say no.
>>>>>>>

[Eric Shepherd]

Note that even right here, Stephanie uses "results" instead of "result."
Case in point, QED. :)

------------------------------------------------------------------------
*From:* Stephanie Hobson
*Sent:* Wednesday, Mar 23, 2016 3:07:37 PM EDT
*To:* Sphinx
*Cc:* mozilla...@lists.mozilla.org
*Subject:* [dev-mdc] Conventions about live samples?

> This matches what both JS Fiddle and CodePen label their results panels so
> I think it's a good conclusion.

--

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

[Eric Shepherd]

I would suggest we use "Results" instead though. Just "Result" sounds...
not quite right. It implies you're only seeing one thing, and it's
pretty common for there to be more than one thing shown. And just
habitually in English, we use "Let's see the results of this test"
rather than "Let's see the result of this test".

I also personally have always put the HTML first just because it
provides the framework atop which everything else rests, even if the CSS
is the focus of the article.

I'm not vehemently opposed to changing that, but I do think it needs to
be considered carefully, because I think having the HTML first gives
context that's lacking if you start with the styles.

------------------------------------------------------------------------
*From:* Stephanie Hobson
*Sent:* Wednesday, Mar 23, 2016 3:07:37 PM EDT
*To:* Sphinx
*Cc:* mozilla...@lists.mozilla.org
*Subject:* [dev-mdc] Conventions about live samples?

> The winner of my in formal survey was "Result" at 13/21 responses.