Re: sample CSS property page: font-size

Great comments. Replies inline marked SIERRA below.  I think it's wise
to keep a tally of the major template/skin enhancements necessary to
produce this suggested design -- will do that.

On Tue, Jan 22, 2013 at 5:55 AM, Chris Mills <cmills@opera.com> wrote:
> My 2p:
>
> 1. Overall I think this is really good, and works nicely as an informative reference page.
>
> 2. I don't think we need much more of a description - this is a reference page and not a tutorial - but I do think we:
>
> * Need to be careful to use more exact wording as to the property's function. "Use this property to set the size of fonts throughout a page" could be misconstrued, and would be better off being written in a more exact and real-world-useful fashion, for example
>
> "This property sets the font size of the element it is applied to, and the descendants of that element. Use it to set the font sizes of your headings, paragraphs and other elements, and — if you decide to employ em or rem units — to define all of the dimensions of the different features on your site."
>
> * Need to point to a suitable tutorial covering the element's usage in more detail, for those who want to learn, not just reference. In the case of font-size, a suitable tutorial can be found at http://docs.webplatform.org/wiki/guides/css_text_styling_fundamentals

SIERRA: I kept the potentially longer (non-listing) description down
to 1 sentence & linked to the tutorial.

> 3. The syntax section is a bit odd, imo - surely it doesn't need a separate line for each type of value? This could get a bit complicated and laborious for more complicated values with more options. Perhaps if we just did something similar to how the specs state it, but a bit less mind bending? So instead of
>
> font-size: absolute-size
> font-size: relative-size
> font-size: length
> font-size: percentage
> font-size: inherit
>
> just say something like
>
> font-size: [ '''absolute-size''' | '''relative-size''' | '''length''' | '''percentage''' | inherit ]
>
> for example
>
> font-size: 3em;
>
> So mark the variables in some way, e.g. make them italicized, then immediately show an example so there is no doubt in the reader's mind.

SIERRA:
I disagree about using formal bracket-style syntax lines, though
I'd otherwise jump at any chance to compress the info. I simply find
them unreadable in many cases. Font-size happens to be easy because
it only allows a single value, i.e.  [this|that|the-other-thing], but it
starts to get crazy with >1 value, some perhaps optional, especially
for shorthand prop's.  I like the way MDN allows a mix of formal &
stacked syntax, the latter doubling as examples. (I mod'ed the syntax
in the example to include CSS comments.) Here's a case where the
one-line syntax might not clarify what happens when you supply
anywhere between 1 and 4 values:
https://developer.mozilla.org/en-US/docs/CSS/border-image-outset
But if I see any syntax like this, I immediately look for alternative
examples: https://developer.mozilla.org/en-US/docs/CSS/border-image
To build such a syntax line, you'd have to either do it manually and
really know what you're doing, or else rely on a far more complex input
template than we have. Perhaps discuss this more on call?

> 4. For the "length" unit types, you've missed out rem, and some of the other less well supported new ones, like vw, vh and vmin. Do we want to include these as well? How far should we go with including more experimental units?

SIERRA:
Since many CSS prop's can specify these units, and since they're
pretty opaque, I'd say the info belongs on another page. For now I
linked to pages within the nonexistent css/units tree. Make sense?


> 5. The interactive utility is useful and fun, but should come at the end, imo, have the Usage notes first. Also, the interactive utility should have a little text display for each of the sliders, to show what their current value is, and you show the CSS being applied from the very beginning.

SIERRA:
Several votes to demote examples & promote usage/compatibility, so OK.
And as you suggested, added default CSS & <output> to reflect each <input>.


> 6. The Usage notes that are there currently are very useful, but I think it also needs a quick typical usage example adding to it, to say something like
>
> "A common best practice is to set the font size on the HTML element as 62.5%, and then using rems or ems to size your child elements. This works well because the default font size of browsers is 16px, and 62.5% of 16 is 10. You can therefore work out the maths for the font-sizes you want to use easier - dividing by 10 is much easier than dividing by 16. Let's look at a quick example"
>
> <!doctype html>
> <html>
>
> <head>
>   <title>My font-size example</title>
> </head>
>
> <body>
>
> <h1>My title</h1>
>
> <h2>My subtitle</h2>
>
> <p>My paragraph</p>
>
> <body>
>
> </html>
>
> The CSS could look like this
>
> html { font-size: 62.5% } /* Set the root computed font size of the document to 10px  */
>
> h1 { font-size: 3.6rem } /* Set the computed value of the h1 element to 36px (36px / 10px = 3.6)  */
>
> h2 { font-size: 2.4rem } /* Set the computed value of the h2 element to 24px (24px / 10px = 2.4)  */
>
> p { font-size: 1.4rem } /* Set the computed value of the p element to 14px (14px / 10px = 1.4)  */
>
> Sounds good, or would you say even this is overkill for a reference doc?

SIERRA:
I added this in much more terse form as a static code example.  Is it
safe to say specifying the initial 62.5% is preferable to 10px because
you want to trust each browser's default "medium" value, but that
means you don't necessarily get the exact pixel values you quote?  I
kind of hand-waved this issue, but do some browsers' default "medium"
not actually compute to 16px?

> 7. Add the following notes into the Compatibility notes section?
>
> IE6-8: Don't support rem values; you need to provide fallback properties, in pixels or other supported values.
>
> <a href="http://caniuse.com/#feat=viewport-units">Support for vh, vw and wmin</a> units is even more limited at present

SIERRA:
I added the additional compatibility item for "rem". Re viewport,
relates to #4 above.  This is not the place to detail compatibility
for that feature.  I did it two ways here, corresponding to wrong &
right IMO:

* Wrong: added a viewport section to the compatibility table. (But
serves as an formatting example for sub-feature support)
* Right: flagged & linked the issue under compatibility notes.

Also note in this section I added a bit of gt/lt syntax to clarify the
exact range of browsers, as an alternative to inexact prose. Also I
added gratuitous concept links, e.g., to "fallback property," as in
the initial metadata table.

--Mike Sierra




> Chris Mills
> Opera Software, dev.opera.com
> W3C Fellow, web education and webplatform.org
> Author of "Practical CSS3: Develop and Design" (http://goo.gl/AKf9M)
>
> On 22 Jan 2013, at 00:57, Jonathan Garbee <jonathan@garbee.me> wrote:
>
>> I think as far as content this page is good as-is. Tutorial information does not belong in this part of the docs. Related Articles would be the place to link off to related tutorial information if available.
>>
>> Although, the usage and compatibility sections should be floated up before the example. They are targets for going to this page, people shouldn't need to scroll to reach the information they seek.
>>
>>
>> On Mon, Jan 21, 2013 at 4:02 PM, PhistucK <phistuck@gmail.com> wrote:
>> A standalone tutorial usually covers several topics (properties) and not a single property.
>> I guess it should be a more detailed summary of some sort, or a short tutorial, like you mentioned.
>> Usually something that starts with, "Use this to...".
>> So, I guess, something like -
>> Use this property to set the font size for text. Font size can be defined using absolute and relative values, among others.
>>
>> It should be a more verbal, yet more detailed (than the summary) explanation that comes before the highly technical syntax/values section.
>>
>> I am not strongly opposed to not having an overview, but I think it makes the article more complete. Maybe it is just a conservative approach.
>>
>> ☆PhistucK
>>
>>
>> On Mon, Jan 21, 2013 at 10:48 PM, Mike Sierra <letmespellitoutforyou@gmail.com> wrote:
>> Can you give me a more detailed overview of what you mean by a
>> "detailed overview"?  ;-)  What kind of info do you think belongs on
>> each prop page rather than in a tutorial? Not that that's necessarily
>> a better idea; just trying to form an idea of where the line between
>> expository & reference should fall.
>>
>> I did avoid some of the more detailed info in the spec on suggested
>> scaling guidelines for keywords, and how they map to headings, but I
>> figured that's more appropriate for implementors.
>>
>> Good point on tables for the compatibility notes & relevant specs; will fix.
>>
>> Re the tables merging desktop/mobile browsers, I figure the two
>> classes of browser are much closer together these days, with a great
>> deal more shared code, especially true for CSS prop's.
>>
>> FYI, that weird animation delay only occurs in webkit, which I filed
>> as bug #107315. I left it in the demo because I figured any weirdness
>> is worth knowing about.
>>
>> --Mike Sierra
>>
>>
>>
>> On Mon, Jan 21, 2013 at 2:44 PM, PhistucK <phistuck@gmail.com> wrote:
>> > Even though it is pretty self explanatory, there is no detailed overview of
>> > the property, there are only notes and examples.
>> > I believe there should be an overview.
>> > The summary is concise, maybe too concise (I do not have ideas)? hehe.
>> >
>> > The compatibility notes are not formatted the way they are currently
>> > supposed to be (a table), which I think is more helpful (the current way,
>> > not you way) for distinguishing the note for every version/edition.
>> > The standards information is also not formatted in a table. Not sure which
>> > is better, though.
>> >
>> > Mixing mobile browsers and desktop browsers at the same line/section is also
>> > not a good idea, in my opinion.
>> >
>> > The example feels a little weird for me, due the first section
>> > growing/shrinking after a delay.
>> >
>> > But, overall, great work!
>> >
>> > ☆PhistucK
>> >
>> >
>> > On Mon, Jan 21, 2013 at 8:21 PM, Mike Sierra
>> > <letmespellitoutforyou@gmail.com> wrote:
>> >>
>> >> In last Thursday's meeting I had an action item to mock together an
>> >> ideal CSS property page for authors to refer to, along with the
>> >> guidance to feel free to reorganize & throw out anything that didn't
>> >> work well. I found it quite difficult to wrestle with the site's
>> >> template system to get what I wanted, so I mirrored it & hacked on the
>> >> page here:
>> >>
>> >> http://letmespellitoutforyou.com/x/webplatform/font_size.html
>> >>
>> >> As you can see, I also mucked with the design a bit to compress the
>> >> page wherever possible, and added an <iframe> to a simple tool showing
>> >> what the CSS actually does. I think all CSS property pages should have
>> >> a similar demo feature, especially once you head towards the
>> >> difficult-to-understand ones like font-size-adjust. (I hope dabblet
>> >> will allow direct embedding & can be modified with option lists for
>> >> CSS keyword property values.)
>> >>
>> >> Any suggestions — content or formatting — please let me know. Thanks,
>> >>
>> >> --Mike Sierra
>> >>
>> >
>>
>>
>
>

Received on Tuesday, 22 January 2013 19:34:25 UTC