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> 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>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
>> @adobejulee
>>
>> From: Scott Rowe <scottrowe@google.com>
>> Date: Tuesday, August 13, 2013 8:35 AM
>> To: Eliot Graff <Eliot.Graff@microsoft.com>
>> Cc: Jonathan Garbee <jonathan.garbee@gmail.com>, WebPlatform Public List
>> <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>
>> 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>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]
>>> *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> 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****
>>>
>>> @adobejulee****
>>>
>>> ** **
>>>
>>
>>
>