Re: Uncomplete CSS property descriptions

Hi, David:


First of all, I'd like to say that I appreciate your input. And I bet others
do as well. I think it's just that we don't have the resources to address
everything. May I suggest that whenever you come across an issue about how
something is written, you file it as a content bug?[1] That way, when
someone does pick up content issues, they can see yours and incorporate your
comments as appropriate.
 
Learning how to write a good bug (or issue) is key in helping fix the
problem. When you go to file a bug, there's a text field labeled
"Reproduction steps". In that, write down the steps you took. Then call out
what you expected from the experience versus what actually happened. Add
examples, as you have, below, and any examples out there in the world where
you think it's been done particularly well. You've pretty much done that in
your email below! We just need to store it for when someone can address it.
 
Secondly, you've mentioned a few times that you're new to the web platform.
New learners may find themselves in the middle of a technical discussion
that does not provide a lot of context. Help for the beginner may be in a
getting started guide, or other aide, such as a a glossary (although that's
considered old-school by some), or a kind of contextual navigation systemŠ
We do have plans to assist beginners, and are working toward a few things.
But again, mostly a lack of resources is holding this up.
 
Finally, one thing that's true: there are a lot of assumptions about the
reader of a reference page. And often it's up to the reader to fulfill those
assumptions ­ without even given a clue! Folks who write references assume:
you use a reference as one component of your bag of learning tools. In line
with this philosophy, it's assumed that you have the right environment set
up (at least a text editor & a modern browser). It's also assumed that
you'll get conceptual information from articles & blogs & videos & such; and
that to learn how to code something, you'll take a class, read a book, take
a tutorial, watch a video, experimentŠ Then, it's assumed you'll use the
reference when you code, pretty much keeping it open to refer to how
something is coded, get clues or gotchas or cool examples for a particular
property or whatever. The brevity of a reference entry, then, is for your
benefit.
 
For example, you asked about the relationship between a CSS style and an SVG
element. Well, if you give the SVG a name, you can identify it in CSS to
manipulate it. But you have to use property names that are SVG words. Notice
how an explanation such as this could really be plugged in to each and every
(CSS/SVG) reference page? That's because it's really a concept. So when you
find yourself asking "what happens around this?" as you have below, it's
assumed you'll look for the answer in an intro or conceptual article. And
when you ask, "how I would use this?" it's assumed you'll find a procedural
­ step-by-step ­ article.
 
It's my opinion ­ and probably not a well-regarded one! ;-) ­ that a
well-written reference page will link to, and smoothly incorporate, key
concepts and procedures. Short of that, we do have examples, which are
supposed to give at least one use case as to both why & how.
 
But, as I said above, this is a philosophy based on a lot of assumptions.
Your experience of the pages on webplatform.org can help improve those
assumptions. So, please do file key experiences you'd like to improve as a
bug in the issues tracker.[1] They are valuable!


HTH


Julee
[1] http://project.webplatform.org/content/issues/new
----------------------------
julee@adobe.com
@adobejulee




-----Original Message-----
From: "David R. Herz" <WPD@theherzes.com>
Organization: WPD
Reply-To: "wpd@theherzes.com" <wpd@theherzes.com>
Date: Tuesday, October 29, 2013 1:38 PM
To: WebPlatform Public List <public-webplatform@w3.org>
Subject: Uncomplete CSS property descriptions
Resent-From: WebPlatform Public List <public-webplatform@w3.org>
Resent-Date: Tuesday, October 29, 2013 1:38 PM

> I made this comment under a different title which received no response.  If
> my perspective is of no value to this community, I'd prefer someone tell me.
> I came here because I figured it would be nice to learn to code properly if
> I am learning anyway.  My basic point here is that a standard should define
> all relevant terms of art, without which it leaves people guessing.
> 
> 
> 
> Now that the CSS properties are essentially wrapped up, I figured I'd give
> them a test run from the newbie's perspective.  I just wanted to take one at
> a time and stick them in a style sheet to see what happens.  I don't know if
> it helps or if I am just outside of the target audience, but for me certain
> things are not clear.  I include the first few properties below. If this is
> helpful, I'll continue.  Feedback is appreciated.
> 
> align-content
> Aligns a flex container's lines within the flex container when there is
> extra space in the cross-axis, similar to how justify-content aligns
> individual items within the main-axis.
> 
> I don't know what a flex container or flex item (from
> http://docs.webplatform.org/wiki/css/properties/flex) is.  The term is not
> defined in any glossary on the site.
> 
> align-items
> Sets the default alignment in the cross axis for all of the flex container's
> items, including anonymous flex items, similarly to
> how justify-content aligns items along the main axis.
> 
> Same with cross and main axis.
> 
> align-self
> Allows the default alignment to be overridden for individual flex items.
> 
> alignment-adjust
> This property allows precise alignment of elements, such as graphics, that
> do not have a baseline-table or lack the desired baseline in their
> baseline-table. With the alignment-adjust property, the position of the
> baseline identified by the alignment-baseline can be explicitly determined.
> It also determines precisely the alignment point for each glyph within a
> textual element.
> 
> I get what the baseline is (thanks to
> http://docs.webplatform.org/wiki/glossary/main), but that doesn't help me
> with a baseline-table.
> 
> alignment-baseline
> 
> Conducting a search, a discussion of this comes up under SVG, but there is
> no CSS reference to give me a clue as to how I would use this, or what
> happens around this, although I suppose I could play to figure this out a
> bit.
> 
> David R. Herz
> wpd@theherzes.com
> 
> 
> 
> 
>