As part of the “examples on top” project, Kadir asked me to investigate writing some “example outcomes”, that show the effect of different values for CSS properties.
The idea here is that the “syntax examples” (i.e. the code block now at the tops of CSS pages: https://developer.mozilla.org/en-US/docs/Web/CSS/margin is good for showing you syntax, but doesn’t show you the effect of these properties. Some live samples do a very nice job of this: https://developer.mozilla.org/en-US/docs/Web/CSS/overflow-y#Result but we thought it might be worth presenting something simple and concise, further up the page.
So I’ve written a few of these in the last day or so: https://developer.mozilla.org/en-US/docs/User:wbamberg/CSS-outcomes, and you can see a couple of them in context here:
https://developer.mozilla.org/en-US/docs/User:wbamberg/Examples_on_top/position-prototype
https://developer.mozilla.org/en-US/docs/User:wbamberg/Examples_on_top/background-size-prototype
Some things I think I’ve learned from this:
-
I think they can be quite effective
-
they are more effort than JS examples but not very much more
-
I’ve used the live sample macro, to get them hosted in an iframe. One problem with that is you get the “Open with…” buttons, that aren’t really appropriate here. It would be easy to adapt the macro so you can suppress those buttons though. Alternatively, maybe there’s a better way to do this that I don’t know about.
-
this doesn’t make sense to do for all properties. For instance, I don’t see how you could build an “example outcome” for
display. -
there’s a question about how they conflict with the existing live examples. Most of the time (for example for position) I think they would complement each other quite well - the live samples are longer with more explanation and detail, the example outcomes gives a compact summary. Sometimes (for example overflow-wrap) I think the example outcome would be basically the same, only with more of the code hidden.
-
I’m still uncertain whether it’s worth doing this now if they will be made obsolete by the interactive sample editor. It will be a while until the live sample editor is fully deployed, and even when it is, these examples might still be useful in some cases.
Feedback’s welcome!