RE: Uncomplete CSS property descriptions

So first, sorry.  I just wanted some response.  I'll figure out how to write
a bug, though I wouldn't have considered these things bugs, just missing
context.  I had searched flex container, and the first things I saw were
shipping containers and Adobe references; I didn't scroll down too much.  I
have found the W3.org reference on the matter.

 

Renoir, as to "hijacking," I call it going with the flow.  This is how ideas
are born, and that's how the world moves forward, so please hijack all you
want.

 

Just a question so I am clear: How do we define this standard, and what
relation should it have to a target audience?  I think of a dictionary,
which can give us the words, but not how to use them, and various grammar
references, which define their own terminology, but don't define the words
used in the everyday world, and usage guides, which assume a certain
vocabulary and grammar to provide for more powerful expression.

 

So taking a current example, should we be able to assume that the users of
this platform know what a flexbox is and the basics of its use, or should we
provide some context?  I see some content has already been added, but the
standard for adding or not should not be whether I whine about it, but
whether it serves to forward the mission and goals of this iteration of the
site.

 

David R. Herz

 <mailto:mr@theherzes.com> wpd@theherzes.com

 

From: Renoir Boulanger [mailto:renoir@w3.org] 
Sent: Wednesday, October 30, 2013 3:15 AM
To: WebPlatform Public List
Cc: wpd@theherzes.com; Julee Burdekin
Subject: Re: Uncomplete CSS property descriptions

 

Hey Julee, David,

 

Like Julee said, we do appreciate your input. 

 

In fact that's the spirit of the project: people to contribute. But as Julee
said, we are not a big team of contributors yet and things might slip by.

 

My role in WPD is to make things run smoothly and, when I can, review some
of the documentation.

 

I am sorry David for hijacking here but I got an idea by reading your answer
Julee.

 

How about we make this answer a new place in our blog?  It could be this
week's post.

 

Regards

 

Renoir 

~

 

On 2013-10-29, at 7:48 PM, Julee <julee@adobe.com> wrote:





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