[CSS Grids] Writing user guides to complete our reference material

[Jean-Yves Perrier]

Hi all!

CSS Grids are coming (in March 2017). Thanks to Sebastian Zartner, we
have a pretty up-to-date set of reference articles, but we still miss
introductory material so that Web devs can learn about grid techniques.

I've spent some time with the specs, our documentation, but also reading
numerous articles and introductory material on the Web, as well as
watching some conferences online and I have a first draft of what I
believe is needed so that Web devs can go from the 'I don't know what
CSS Grids are' to 'I know what they are, how they work, now I can start
using it', the 2nd step on the proficiency scales.

Take some time to have a look at them; I'm especially interested about
comments around the structure and the completeness. Don't spent too much
time on the wording of the articles (they can be changed later).

Thank you all for your help!

Jean-Yves

vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv

CSS Grids user guides (first draft)

CSS Grids
Overview page, links to all CSS grids resources we have.

Basic concepts of a CSS Grid
Describes the basic notions around CSS Grids: what are a grid,
containers, items, lines, tracks, cells, areas, rows, columns, gutters,
nested grids, (sub grids, in the future)
Using grid templates to describe a CSS Grid
Uses grip-templates(-columns, -rows) to describe different CSS grid
and succinctly explains how to position grid items into it (link to more
in-depth articles)
Interaction between CSS Grids and the writing mode
Explain the numeration of grid lines, and -start & -end names, and
their meaning w/ different writing-modes.
Laying out using anonymous line-based placement in a CSS Grid.
In-depth explanation of how to place CSS items using numbered grid
lines
Laying out using named grid lines
In-depth explanation of how to place CSS items using named grid lines
Laying out using named area (and implicitly named grid lines)
In-depth explanation of how to place CSS items using areas (ascii’s
description in grid-template-areas) and -start/-end implicitly named
gird lines
Mastering box alignment within a CSS Grid
How to use box alignment properties to align an item inside its
grid cell.
CSS Grids and accessibility
How grids helps accessibility (by decoupling semantic ordering and
layout ordering), what are the risks (tab ordering, HTML flattening) and
how to mitigate them
CSS Grids and progressive enhancement
How to introduce css grids today, and how to use it w/ PE, media
queries and feature queries.
Traditional layouts w/ CSS Grids: (2 articles, very concrete)
- Holy grail layout
- 12-columns layout

Glossary entries (w/ graphics):
Grid Lines
Grid Tracks
Grid Cell
Grid Area
Gutters
Grid row
Grid column


--
Jean-Yves Perrier
Senior St. Project Manager, Developer Documentation / MDN

[Chris Mills]

Hi there,

This proposed article set looks pretty good to me. I had a few thoughts:

1. A section on how Grids relates to other modern layout mechanisms would be useful - you tend to get quite a bit of confusion on where to use grids, and where to use flexbox, for example.

2. The "Traditional layouts w/ CSS Grids” article seems to be taking slightly the wrong direction, IMO. When you do grid layout, you always tend to start with a set number of columns as a basis for your layout to go on top of (12 being the most common), and implement layouts on top of that (e.g. holy grail, 3 column, etc.) So 12-columns is not really a type of layout — it’s a basis for putting layouts on top of? I’d explain that first, and then show how to d a couple of layout types on top of it, like holy grail, perhaps with some variations of image and text column width in different places to highlight to flexibility the 12 columns gives.

3. As a follow on from my last sentence on 2., I’m not sure if it is mentioned anywhere in the proposed set, buy you should definitely talk about how to offset the position of images/other page features - a very common need.

Best,

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide

[Sebastian Zartner]

Hi everyone,

the proposed set of pages also looks very good to me. Thank you for
pushing on it, Jean-Yves!
I also agree on Chris' points 1 and 3. Regarding point 2, I assume
it's just the title that has a bit of a confusing name. That grid
layout is based on columns and rows will already be explained in
"Basic concepts of a CSS Grid". So, I assume the title for the last
point should rather be something like "Common use cases for CSS Grid"
or "Common layouts where CSS Grid can help out". I see 12-columns as a
basic layout type. The holy grail can be built on top of it, though
its use cases rather lie on splitting a page into 12 equally sized
parts.

Besides these new articles, I'll start updating the property
descriptions to the current specification and implementations.

Sebastian

[William Bamberg]

Will there be an examples repo, like
https://github.com/mdn/css-grid-examples, to back up these guides? If so,
is it worth mentioning explicitly?

On Mon, Jan 9, 2017 at 6:26 AM, Jean-Yves Perrier <jype...@gmail.com>

[Chris Mills]

> On 11 Jan 2017, at 23:43, Sebastian Zartner <sebastia...@gmail.com> wrote:
>
> Hi everyone,
>
> the proposed set of pages also looks very good to me. Thank you for
> pushing on it, Jean-Yves!
> I also agree on Chris' points 1 and 3. Regarding point 2, I assume
> it's just the title that has a bit of a confusing name. That grid
> layout is based on columns and rows will already be explained in
> "Basic concepts of a CSS Grid". So, I assume the title for the last
> point should rather be something like "Common use cases for CSS Grid"
> or "Common layouts where CSS Grid can help out". I see 12-columns as a
> basic layout type. The holy grail can be built on top of it, though
> its use cases rather lie on splitting a page into 12 equally sized
> parts.

Yeah, still sounds like a grid to me ;-)

>
> Besides these new articles, I'll start updating the property
> descriptions to the current specification and implementations.
>
> Sebastian
>
> On 10 January 2017 at 15:08, Chris Mills <cmi...@mozilla.com> wrote:
>> Hi there,
>>
>> This proposed article set looks pretty good to me. I had a few thoughts:
>>
>> 1. A section on how Grids relates to other modern layout mechanisms would be useful - you tend to get quite a bit of confusion on where to use grids, and where to use flexbox, for example.
>>
>> 2. The "Traditional layouts w/ CSS Grids” article seems to be taking slightly the wrong direction, IMO. When you do grid layout, you always tend to start with a set number of columns as a basis for your layout to go on top of (12 being the most common), and implement layouts on top of that (e.g. holy grail, 3 column, etc.) So 12-columns is not really a type of layout — it’s a basis for putting layouts on top of? I’d explain that first, and then show how to d a couple of layout types on top of it, like holy grail, perhaps with some variations of image and text column width in different places to highlight to flexibility the 12 columns gives.
>>
>> 3. As a follow on from my last sentence on 2., I’m not sure if it is mentioned anywhere in the proposed set, buy you should definitely talk about how to offset the position of images/other page features - a very common need.
>>
>> Best,
>>
>> Chris Mills
>> Senior tech writer || Mozilla
>> developer.mozilla.org || MDN
>> cmi...@mozilla.com || @chrisdavidmills
>>

[Jean-Yves Perrier]

On 11/01/2017 23:54, William Bamberg wrote:
> Will there be an examples repo, like
> https://github.com/mdn/css-grid-examples, to back up these guides? If
> so, is it worth mentioning explicitly?
>

Yep, good point. Added.