The problem with writing a flexbox chapter is that I sometimes have to spend 2 hours to research a single paragraph. And that's with extensive handholding by @tabatkins in person.
2
1
1
7
I had much the same experience writing the paragraphs about inline text layout for the first edition of CSS:TDG, except it was @davidbaron and @Hixie extensively holding my hand via email for a couple of weeks.
2
1
8
In retrospect what we SHOULD have done is change the spec to be clear.
1
3
I think that specs should contain a fairly short, non-normative section that introduces key concepts in not-too-technical language. Then the actual spec starts with the implementor-specific version.
1
1
2
Agreed. I think the movement to have explainers has similar motivation, although some folks feel strongly that explainers should be separate documents (I don't). Whether separate or not, there's significant risk that the non-normative part gets out of sync.
1
1
Maybe create the explainers only when the spec is later in its lifecycle? OK, that doesn't solve the problem entirely ...
1
Plus explainers are useful for, well, explaining the topic *before* you've nailed down the precise text.
1
1
Explainers are useful for answering the question of "what problem is this spec trying to solve" (which arguably should also be in the introduction!)
1
1
3
Replying to @gsnedders @tabatkins @ppk @Hixie @meyerweb
Explainers are also useful for iterating on a solution at a high level, before everyone agrees what the right solution is, and well before it's time for precise spec text. To be useful for that, they need to be understandable. They might also need to go deeper on key questions.

Aug 24, 2021 · 6:51 PM UTC
2