Creating a CSS cookbook on MDN?

MDN
#1

Hi all,

As part of her recent contributions to MDN, Rachel Andrew has started thinking about a CSS Cookbook type resource on MDN. The idea would be that we’d have common code patterns, each on a single page, with explanations of how each one works, what it is used for, etc. Each would be best practice, and usable in your own projects.

She has written up her initial thoughts here, and I’ve also added some ideas:

Obviously, before we start such a major chunk of work, we want to get feedback! Please let us know your thoughts, ideas, and concerns.

1 Like
#2

I think this is a really really really good idea :).

If I were doing this, I’d make it very “code-first” - meaning, make it primarily about code rather than explanatory prose. I’d have a bit of prose explaining what the recipes are doing and how, but mostly let the code speak for itself.

Relatedly I’d be keen to make it very easy to interact with the recipes. For me it’s much easier to understand what a recipe is for when I can see and interact with the result, compared with reading the description of it. So I’d present that front and centre.

I’d also be wary of centering it on the Wiki. I think it would be good for the “master copy” of the recipes to live in GitHub, so they’re easy for people to fork and modify. But then duplicating code chunks into Wiki pages is going to make it hard to maintain. I have done this for “Your second WebExtension” and to be honest it’s a bit of a nightmare keeping the code in the article in sync with the GitHub code.

So (again, this is just my opinion) I’d make the thing live in GitHub and the Wiki side would just be a catalogue of the examples, listing things like name, description, possibly screenshot.

It’s not an exact analogy, but to present examples of WebExtensions, the primary asset is the repo (https://github.com/mdn/webextensions-examples). I then have a single index page in the Wiki, that’s generated using a KumaScript macro from a metadata file that also lives in the repo. I also have links from individual APIs to relevant examples, that are also generated by a KumaScript macro from the same metadata file.

This means that I only have to maintain the examples in the GitHub repo, and I know that the pointers in the Wiki will be kept up to date.

#3

I’d prefer it if we at least had the ability to mirror the contents of a GitHub page or whatever into MDN, possibly by just using a macro that fetches the contents of a GitHub page and injects it into MDN. Being able to see the stuff on-site would improve ease-of-use IMO.

Beyond that, though, I think this is a good idea to explore.

#4

I also agree that the code should be front and center. Quick overview of what problem the code is useful to solve, then bam straight into the code. After the code, perhaps, a longer explanation of how it all works, where helpful.

#5

I agree, in terms of the prose I was mostly thinking of using it as a route into the docs and guides we already have. So for example, if I created an example Media Object which used Grid, the text would explain my decision (why use Grid rather than Flexbox) and then link to the places we already have for detail on implementation, so the property refs, the Grid Guide articles etc.

I might create a sample one for bikeshedding anyway before starting to create a whole lot.

#6

Yeah, I think a good next step would be to create a couple of sample pages to show what we’d be dealing with.

You could put them underneath my user page while we figure out the details: https://developer.mozilla.org/en-US/docs/user:chrisdavidmills

Maybe even create a prospective landing page and a couple of child recipe pages below it?

I’ve got a plan for showing the code using the interactive examples editor, but will probably need to talk to Will to make sure that’d be suitable. For now, just dump the code in the page however you like.

#7

So I made a rough start on this, with a landing page and sample pattern. Code is just linked to CodePen to save me trying to format it. I haven’t linked up every property name etc. but this is going with the approach of not having a walkthrough of the code, just highlighting major features.

The actual example is a little rough, the idea being to bikeshed the page layout/what we include, but I wanted to do something that had a bit of complexity not a really small example.

#8

This is a good start. I’ll give it a closer look soon (tomorrow I hope). Worth noting: we use sentence case for titles and headings on MDN, rather than capitalizing every word. :slight_smile:

Sheppy

#9

I actually never thought to ever mention this to Rachel in all the years of editing her stuff on MDN; no idea why :wink:

#10

@rachelandrew so I’ve edited the main page and the sample recipe, and made a few changes, but nothing massive.

I added a description column into the table on the main page.

I think the only thing missing from the recipe page is being able to show the actual code. I think we should try using an interactive example to both show the HTML and CSS, and the rendered result, and allow the reader to play around with it live.

But I think this would require a vertical layout — show the rendered example first, and the tabbed editor below it.

@wbamberg, can the tabbed editor already do this?

#11

@wbamberg, can the tabbed editor already do this?

No.

But a bigger issue is: if we want to use the interactive examples system for this, where does the recipe code live?

  • In the interactive-examples repo? I think this will be a big obstacle for people who want to check out the code and play around with it, because they have to deal with all the interactive-examples scaffolding. It’s not really designed for this. As I said upthread, it would be good if this cookbook makes it as easy as possible for people to fork/clone/modify the examples in their own environments.

  • In both the interactive-examples repo and the (say) css-cookbook repo? Then we have the problem of keeping them in sync.

  • Or do we modify interactive-examples to be able to use code that lives in a different repo? This sounds complicated (and also perhaps like scope creep for interactive-examples).

I would suggest, as a first attempt, to just show the result in an iframe containing a GitHub page that uses the mdn/css-cookbook code, and to include links to the source files in mdn/css-cookbook.

#12

I agree with @wbamberg that taking a fairly direct approach, separate from existing models, is a good starting point. But if we intend this to be a long-term feature of MDN, we probably need to at least start to consider how it should be done “for real.”

At a minimum, I would definitely say that we need to keep in mind (as we think about a future new MDN platform) things like being able to have repositories of examples that can be presented and/or documented and/or experimented with directly inline on MDN pages, while having the code also in a proper repository and available for fork, clone, commit, and so forth operations.

#13

OK, thanks for the comments; good thoughts here @sheppy and @wbamberg.

So for now @rachelandrew, just add your examples into a new location (a subfolder inside https://github.com/mdn/css-examples probably makes sense), and then we can use the EmbedGHLiveSample.ejs macro to embed them, and also decide whether we want to show code snippets, or just link to the source?