Re: sample CSS property page: font-size

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

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.

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?

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. 

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?

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

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 10:55:42 UTC