Re: Uncomplete CSS property descriptions

Hi, David–

The reference pages might be considered "pro" pages. They are there to 
provide a drill-down into details on a property, method, element, or 
whatever.

We can't make every reference page talk about all the concepts that are 
related to it; that won't scale.

Instead, what we'd like to do is link from those pages to tutorials that 
give some background, context, real-world examples, and other supporting 
concepts. For newbies, those should be the first point of contact with 
the material.

We aren't there yet; we don't have all the tutorials we'd like, but 
we'll continue to work on that.

For your specific question: are we assuming that the site's users 
already know what flexbox is? Right now, yes… it's a well-known concept 
among professional developers and designers, though they may still need 
reference material for it. As we get more tutorials and related content, 
that answer will shift to "no, we don't assume prior knowledge".

Regards-
-Doug

On 10/29/13 11:57 PM, David R. Herz wrote:
> 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
>
> wpd@theherzes.com <mailto:mr@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
> <mailto: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 onwebplatform.org
> <http://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 <mailto:julee@adobe.com>
>
> @adobejulee
>
> -----Original Message-----
>
> From: "David R. Herz" <WPD@theherzes.com <mailto:WPD@theherzes.com>>
>
> Organization: WPD
>
> Reply-To: "wpd@theherzes.com <mailto:wpd@theherzes.com>"
> <wpd@theherzes.com <mailto:wpd@theherzes.com>>
>
> Date: Tuesday, October 29, 2013 1:38 PM
>
> To: WebPlatform Public List <public-webplatform@w3.org
> <mailto:public-webplatform@w3.org>>
>
> Subject: Uncomplete CSS property descriptions
>
> Resent-From: WebPlatform Public List <public-webplatform@w3.org
> <mailto: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 <mailto:wpd@theherzes.com>
>

Received on Wednesday, 30 October 2013 04:59:16 UTC