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

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