Re: Message "Do not check this box without first reviewing with the community on the e-mail list."

Thanks, everyone. OK. I'm thinking that this UI is confusing. Mike Sierra thought it meant that you should not add an example unless you emailed the community.

Maybe the note should say something more direct to the editor, such as: "This article does not need an example. (This box should be checked only in rare cases. Most articles need examples.)" ?

J
----------------------------
julee@adobe.com
@adobejulee

From: Scott Rowe <scottrowe@google.com<mailto:scottrowe@google.com>>
Date: Tuesday, August 13, 2013 8:35 AM
To: Eliot Graff <Eliot.Graff@microsoft.com<mailto:Eliot.Graff@microsoft.com>>
Cc: Jonathan Garbee <jonathan.garbee@gmail.com<mailto:jonathan.garbee@gmail.com>>, WebPlatform Public List <public-webplatform@w3.org<mailto:public-webplatform@w3.org>>
Subject: Re: Message "Do not check this box without first reviewing with the community on the e-mail list."
Resent-From: WebPlatform Public List <public-webplatform@w3.org<mailto:public-webplatform@w3.org>>
Resent-Date: Tuesday, August 13, 2013 8:36 AM


The examples checkbox tells us whether or not to include the article in the results of a query for articles needing examples. If the article should have an example, and the checkbox is not checked, then the article will display the "Needs Examples" flag and it will be listed in the results of a query for articles needing examples, like those in the Getting Started page (http://docs.webplatform.org/wiki/WPD:Getting_Started#Develop_code_examples).

This is essential information that helps guide contributors who want to develop code examples. As to whether it belongs in a conceptual article, that is up to the beholder: if you think a conceptual article needs an example, go ahead and leave the box unchecked.

~Scott



On Mon, Aug 12, 2013 at 2:27 PM, Eliot Graff <Eliot.Graff@microsoft.com<mailto:Eliot.Graff@microsoft.com>> wrote:
My guess is that the logic for this comes from when Alex et al were developing the templates. I would imagine that Alex and Chris Mills would be the best bet for understanding the historical reasons behind it, though like you, I cannot fathom why we’d suppress samples on a page like this.

From: Jonathan Garbee [mailto:jonathan.garbee@gmail.com<mailto:jonathan.garbee@gmail.com>]
Sent: Monday, August 12, 2013 2:21 PM
To: WebPlatform Public List
Subject: Re: Message "Do not check this box without first reviewing with the community on the e-mail list."

It looks to me as if this checkbox is supposed to make it so the example isn't shown on the page. However that seems counter-productive and useless.

In some cases concepts should have code examples. It is perfectly valid for them to be there.

So, if this isn't what the checkbox does then what does it do? And further why would a warning like this be put on something without consulting the ML first? (Unless it is just a discussion I couldn't find, in which case a link to the discussion of it after the warning would be nice.)

On Mon, Aug 12, 2013 at 4:49 PM, Julee <julee@adobe.com<mailto:julee@adobe.com>> wrote:
Hi, folks:

When editing a concept page,[1] I can across this note:

Examples Section

Not required (suppresses printing of the entire section when checked)

Note: Do not check this box without first reviewing with the community on the e-mail list. This check box should be used only in rare cases.


Could someone please help me understand: is it OK to add examples to concept pages? What does this message mean to prevent or encourage?

Thanks much!

Julee
[1] http://docs.webplatform.org/w/index.php?title=css/concepts/overset&action=formedit
----------------------------
julee@adobe.com<mailto:julee@adobe.com>
@adobejulee