Making a new content kit

This guide takes you through the process of creating a new MDN content kit. To follow on with the process, compare the content kit template you will be using as a starting point with the sample content kit — Working with HTML5 Video: Adding captions and subtitles.

General steps

  1. First of all, clone the content kit template.
  2. Make a copy of the template directory and rename it to something memorable, preferably involving content-kit.
  3. Delete the .git directory and .gitignore files from inside the directory, so that you can distribute your content kit as its own standalone Github repo later on (or in some other way if wished.)
  4. Inside the content kit directory, open up the index.html file in your favourite text editor, and start filling in the sections. A detailed guide to filling this in is included in the "Filling in the HTML index" section below.
  5. Inside the demo directory, include demo resources to demonstrate the kit's subject technology. See the Building a demo section for tips on writing a good demo.
  6. Inside the slides directory, include a slideshow for presenting the topic. See the Writing a slideshow section for tips on writing a good demo.

Filling in the HTML index

  1. Fill in the content kit's <h1> and <title> elements with the name of your repo, in our case "Working with HTML5 Video: Adding captions and subtitles."
  2. Fill in the three paragraphs below the <h1> with the described information. You can get a better idea by looking at our intro example.
  3. Fill in the versioning information section as instructed in the template.
  4. "What should the presenter have?": think about what you'd need to confidently teach other people on this subject — you're not just learning it yourself. For example, if learners need intermediate JavaScript, you probably need expert JavaScript knowledge so that you can answer curveball questions and debug their code problems. Also include information on what hardware/software they need. This may not be obvious to all.
  5. "What should the audience have?": what do the audience need for the presentation? What level do they need to be at to be able to learn a decent amount from it?
  6. "Learning objectives": Fill in the main things the audience will learn from the presentation.
  7. "Links to resources": Fill in links to all the things you and your audience will need during the course of the presentation/demo. If possible, have an archive of these things available locally in case the network is down when you come to run the session..
  8. The first section should contain the items immediate relevant to the content kit, such as the kit's source code, tutorial, slides or whatever you felt was appropriate to include. See below sections for notes on creating slides, demos, etc.
  9. The second section should contain supporting documentation, such as a tutorial showing how to build up the content kit demo and references docs for the technologies involves, if attendees want to study the subject more deeply, and/or if the presenter wants to deliver some kind of extended workshop on the subject matter.

Presentation setup

This section is intended to provide the presenter with all they need to present confidently on the subject. Slides are essential. A video showing a previous presenter giving the talk would also be useful, but isn't essential, at least not immediately. It would be an idea to capture the first run of the content kit on video and provide that at a later date.

The notes are intended to give the presenter some guidance on how to run the presentation. It is a good idea to always include timings to show the presenter how long they'll need to run through the presentation, perhaps with or without a live demo, or running a tutorial.

Demo setup

This section is intended to provide the presenter with the instructions they need to confidently run a demo about the content kit subject. It includes sections to provide:

Active learning

In your content kit, you are strongly advised to include some kind of active learning mechanism in your content kit slides, to break up the presentation a bit. This may include links to demos that the audience can play with, live coding sections, demos that include participation from the audience, etc.

the rationale behind this is really two fold:

Frequently asked questions (FAQs)

This section allows you to include an FAQ to cover some of the most common questions you might be asked, as a time saving aid for the presenter during Q&A. If you have an existing FAQ resource, you could always link to that instead.

Building a demo

To create a good demo, you need to write a code package that is as self-contained and easy to present as possible.

  1. Ideally the demo should run offline, and not require much setup. If either or both are not possible, provide clear, detailed instructions on how to install/setup the demo, including any necessary hardware steps. There is a space in the content kit index file to include these instructions, but you should consider including the instructions in the demo files too, especially if you are going to distribute the demo in a separate repo.
  2. If you are intending to include a tutorial element in your content kit, it is a good idea to include different versions of your code — a starting template, a final version, and an intermediate version for each step in the tutorial. This will allow the audience to pick up the tutorial at any point, and also check their code against the tutorial if they find themselves going wrong.
  3. ONLY include code that is relevant to the content kit. A large amount of non-relevant code can easily distract or confuse the audience. For example, our demo content kit on HTML5 video captions and subtitles only really includes JavaScript and HTML. A very minimal amount of CSS has been included for clarity, but no more.
  4. Write your code as cleanly and understandably as possible, even if it is not the most efficient way to do it. The aim is comprehension, not efficient code (ok, a content kit on "efficient JavaScript" might be an exception to this rule...) Also stick with pure technology where appropriate; for example if you are teaching a specific JavaScript API, writing all the surrounding DOM calls using jQuery could easily limit comprehension. The audience would then need jQuery as an extra level of knowledge on top of JavaScript.
  5. Make sure you use resources that you have the rights to use. Copyrighted images and videos, for example, could cause legal problems. Use your own or find something with a permissive license. For example, our demo content kit uses an excerpt from Sintel, an open source animation created by The Blender Foundation.

Writing a slideshow

When writing a slideshow, you need to consider both the implementation technology and the content of the slides. We'll consider these two aspects separately.

Slide implementation

When choosing a technology to implement slides in, you can obviously choose whatever you like. However, we would recommend that you use open web technologies to implement your slides. Programs such as Powerpoint and Keynote work well, but they are not so good for distribution — you cannot guarantee that others who wish to make use of the slides will have those programs, and web delivery of these formats is poor.

If you need to use such a program, you are advised to export the result to .pdf format, and upload it to a site such as Slideshare.

Creating a slide deck that looks good in web technologies can take some time, so you would be advised to use an online tool such as slides.com, or a slide framework or template, such as the Shower presentation engine.

We used Shower for the Working with HTML5 Video: Adding captions and subtitles slides. It is fairly easy to use and looks good.

One thing to make sure of before you settle for a technology in which to present your slides is that your slides will be accessible both offline, and online (for wide distribution).

Slide content

Now let's think about what content to include in the slides. There are a lot of opinions on what makes a good slide deck, but below we've included just some basic advice on making your slides readable, and usable for an effective presentation.

Optional items

So far we've run through all the items that we feel are mandatory for a content kit. But you needn't stop there — it is perfectly ok to add optional extra parts that can be called upon if deemed necessary.

Here are some extra content ideas that you may want to include: