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

Thanks, Scott! Any way to put the checkbox before the label? With the checkbox all the way at the end, it looks like we're telling the editor "This article does not need an example."

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

From: Scott Rowe <scottrowe@google.com<mailto:scottrowe@google.com>>
Date: Tuesday, August 13, 2013 9:47 AM
To: Mike Sierra <letmespellitoutforyou@gmail.com<mailto:letmespellitoutforyou@gmail.com>>
Cc: julee <jburdeki@adobe.com<mailto:jburdeki@adobe.com>>, Eliot Graff <Eliot.Graff@microsoft.com<mailto:Eliot.Graff@microsoft.com>>, 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."

Thanks folks, I've updated the form with Julie's edits.
~Scott



On Tue, Aug 13, 2013 at 9:32 AM, Mike Sierra <letmespellitoutforyou@gmail.com<mailto:letmespellitoutforyou@gmail.com>> wrote:
Was actually confused that examples seemed to be as fixed a requirement for concepts as they are for properties. Some, like css/concepts/inherited, seem naturally simple enough to express in a short paragraph.  Or perhaps this is the proper role of the "Glossary" template?  Turned out css/concepts/overset was complex enough to benefit from several examples.

I authored most of the css/concepts content as needed for click-thru's for property-page templates & for CSS Regions, so I realize I'm to blame here. (BUGS: there are no links to existing "animatable" and "applies to" concepts. Also no "media" concept, and click-thrus such as "visual" don't resolve.)

Also confused that some concept pages were marked as needing examples & some weren't (e.g. css/concepts/region, /region_chain, /named_flow, /fragment).

--Mike S



On Tue, Aug 13, 2013 at 11:53 AM, Julee Burdekin <jburdeki@adobe.com<mailto:jburdeki@adobe.com>> wrote:
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<mailto: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