Lesson Plan Style Guide

The Make WordPress Training style guidelines are a reference point to maintain consistency while developing new lesson plans.


Topics Topics


Content #

Resources Resources

The Make WordPress Training lesson plans are a project of WordPress.org. As such, lesson plans should not incorporate content that refers to or details elements of the following unless the Training Team has collectively decided that an exception makes sense:

  • WordPress.com
  • Paid services and resources, including plugins and themes

Top ↑

Tone Tone

Write in script format. The reader should feel that the speaker is an instructor explaining something clearly to them.

Address the audience directly by writing in the second person (i.e. you, not we).

Correct
Log in to your WordPress Admin Screens.

Incorrect
Next, we need to log in to WordPress.

Top ↑

Grammar Grammar

Use standard English grammar for all lesson plans unless a lesson plan is originally written in or translated into another language. If English is your second language, that is OK! The copy editing process includes editing for grammar usage.

You should write lesson plans using:

  • complete sentences.
  • WordPress elements as regular nouns. For example, the words, theme, post, user, etc., are not proper nouns.
  • Oxford commas, which include a comma before the final conjunction, normally and or or.
  • active voice. There are times when the passive voice is appropriate, but they should be rare.

Structure #

All lesson plans follow the same structure. The definitive structure is found at the Repo Structure and Lesson Plan Template in the Training Team Github repository. That document functions both as a template for starting new lesson plans, as well as a description of the purpose of each section and its proper structure.

Please ensure that a lesson plan contains each of these elements, both when originally created and through all subsequent revisions. If you need examples of well-formed sections, please see lesson plans that are complete.


Assets #

Top ↑

Approved Themes Approved Themes

Use one or more of the following themes in your demos:

Top ↑

Images Images

Images should be full size. Don’t include thumbnails that readers have to click on to see unless absolutely necessary.

Screenshots Screenshots

All screenshots that show an operating system should be taken using a Mac computer. All other screenshots can be taken using other operating systems.

To take screenshots that look great, resize your browser window. By resizing down, you can take screenshots of the specific areas of the screen that you are referring to. All browser elements should be cropped out of the image. The exception to this guideline is if you need to show a code inspector in your screenshot.

Code Inspectors

If you need to show a code inspector in your screenshot, please use Firefox’s or Chrome’s native inspector. If a particular code inspector is required for students to follow along with the lesson plan, indicate this requirement in the Teacher Notes for the lesson plan.

Notations

Make all notations on screenshots using simple arrows and icons, and use red as the primary color for any notations. If you need a secondary color for the annotations, use blue. In general, keep notations to the minimum needed to make clear a point in the lesson.

Top ↑

Placeholders Placeholders

Placeholder images should be sourced from Placekitten. This is done using a URL that calls the image from the site using the size you prefer, such as
<img src=“http://placekitten.com/g/500/300“>, which displays the following image:

Top ↑

Naming Conventions Naming Conventions

All filenames should be descriptive of the image, all lowercase, and contain no spaces: e.g. kitteninbasket.jpg is consistent with the style guide and Kitten in Basket.jpg is not.

Top ↑

Content Content

Top ↑

Sample Content Sample Content

If you need to include placeholder content in your demo theme, use the Theme Unit Test Data. There is inline documentation at the top of this file with instructions on how to import the content into your WordPress installation.

In instances where the demonstration requires sample content to be added during the demo or in the exercises, the Theme Unit Test Data may not be appropriate to use in isolation. In this case, use the lipsum.com Lorem Ipsum generator to create this content.

Top ↑

Sample Plugins Sample Plugins

If you need to include placeholder plugins in an example, use the Monster Widget to add the default WordPress plugins to the sidebar of your lesson plan’s sample theme.

Top ↑

Colors Colors

When producing diagrams, charts, etc. use the official WordPress color palette:

Top ↑

Blue Blue

  • Pantone 7468
  • CMYK 97, 44, 26, 3
  • Hex #21759b
  • RGB 33, 117, 155
  • HSL 199, 79%, 61%

Top ↑

Orange Orange

  • Pantone 1665
  • CMYK 6, 86, 100, 1
  • Hex #d54e21
  • RGB 213, 78, 33
  • HSL 15, 85%, 84%

Top ↑

Grey Grey

  • Pantone Black 7
  • CMYK 65, 60, 60, 45
  • Hex #464646
  • RGB 70, 70, 70
  • HSL 0, 0%, 27%

Top ↑

Light Blue Light Blue

Although not a part of the official WordPress color palette, this light blue is commonly used as an accent color.

  • CMYK 16, 3, 0, 0
  • Hex #d3e7f8
  • RGB 211, 231, 248
  • HSL 208, 15%, 97%

Formatting #

Top ↑

Basic Conventions Basic Conventions

  • Use W3C HTML and CSS Recommendations to separate document markup (HTML) from inline styling preferences (CSS).
  • Use ordered and unordered HTML lists.
  • Use HTML header tags in the correct order from h2 – h6. Do not add inline styling to headers.
  • When referring to menu items, use the format Pages > Add New.
  • Do not use empty paragraph or header tags to force spacing between content elements.

Top ↑

Emphasized Text Emphasized Text

Use strong tags to make important points stand out or to indicate instructions: e.g. Create a Child Theme that is a “child” of another theme (the Parent Theme).

If you want to alert the user to something, the Training Team has placed a variety of icons in GitHub that you can use for various purposes using Markdown. These replace the shortcodes previously used, as indicated in the following.

  • For informational messages (formerly the [ info ] shortcode), preface the paragraph with the following code:

> ![](https://raw.githubusercontent.com/wptrainingteam/contributor-resources/master/images/info.png)

  • For tips (formerly the [ tip ] shortcode), preface the paragraph with:

> ![](https://raw.githubusercontent.com/wptrainingteam/contributor-resources/master/images/lightbulb.png)

  • To alert readers to important messages (formerly the [ alert ] shortcode), preface the paragraph with:

> ![](https://raw.githubusercontent.com/wptrainingteam/contributor-resources/master/images/flag.png)

  • To warn readers about something that is particularly precarious (formerly the [ warning ] shortcode), preface the paragraph with:

> ![](https://raw.githubusercontent.com/wptrainingteam/contributor-resources/master/images/dismiss.png)

  • To give the user ideas about the materials (new with our move to GitHub), preface the paragraph with:

> ![](https://raw.githubusercontent.com/wptrainingteam/contributor-resources/master/images/icon-idea.png)

Use the Markdown code like this:

> ![](https://raw.githubusercontent.com/wptrainingteam/contributor-resources/master/images/icon-idea.png) To check the appearance of changes without publishing them, click the “Preview Changes” button. This will open another browser tab to display what your page or post will look like on the site.

The result in the final Lesson Plan will look like this:

Top ↑

Code Examples Code Examples

Use standard Markdown syntax for each language to wrap code samples. For indentation, use 4 spaces. You can find a cheatsheet in the Code and Syntax Highlighting section of the Markdown Cheatsheet.

Top ↑

File Names File Names

File names and other inline code snippets should all be wrapped in back ticks `.

Correct
`style.css`

Incorrect
style.css


Issues #

If you encounter a situation where you need to leave a lesson in an unfinished state–such as if you need input on some aspect of the lesson or later need to update images–you should add a To Do section at the top of the lesson using the info short code (see the Emphasized Text section in Formatting above). Format the To Do section like this:

![](https://raw.githubusercontent.com/wptrainingteam/contributor-resources/master/images/info.png)To Do

  • Replace images captured in Windows with those captured on a Mac to be consistent with the existing images
  • Resolve the issues with the best way to fitzblat the snagglepark

Accessibility #

Top ↑

General Items General Items

  • Do not underline words that are not links.
  • Do not use all caps within content.
  • Use HTML to convey textual information as much as possible instead of using PDF or image formats.

Top ↑

Use descriptive links instead of generic text: e.g. “We are using the Twenty Thirteen theme.” is consistent with the style guide and “Find the Twenty Thirteen theme here.” is not. On pages that contain multiple links, ensure that each link text is unique – unless you are linking to the same resource in more than once place.

Top ↑

Images Images

Use descriptive alt text on all images: e.g. “page attributes section of edit page screen” and not “image” or other text which does not adequately describe the the image.

Top ↑

Multimedia Multimedia

Make sure equivalent alternatives are available for audio/video content. For example, use Closed Caption service for videos.

Top ↑

Abbreviations Abbreviations

Avoid the use of jargon, abbreviations and acronyms whenever possible. If you really do need to use an abbreviation, use the full, expanded version first, followed by the abbreviation in parentheses (brackets). Alternatively, use correct abbreviation markup such as:
[html]W3C[/html]