W3C home > Mailing lists > Public > public-webplatform@w3.org > October 2013

Re: Uncomplete CSS property descriptions

From: Renoir Boulanger <renoir@w3.org>
Date: Tue, 29 Oct 2013 21:14:49 -0400
Cc: wpd@theherzes.com, Julee Burdekin <julee@adobe.com>
Message-Id: <044B59A6-A17D-4F06-B34A-0FE2C8D2F1A5@w3.org>
To: WebPlatform Public List <public-webplatform@w3.org>
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


Received on Wednesday, 30 October 2013 01:14:58 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:13:55 UTC