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. Below is a list of elements found in each lesson plan, with a brief description of each. When creating a new lesson plan, ensure that it contains each of these elements.

Specific formatting concerns may apply to each section as outlined below.

Top ↑

Description Description

The description should be a short paragraph explaining what is covered in the lesson plan, written in full sentences. This should be text that can be copied and used in a Meetup or workshop description.

Here is a nice example. It is indented here to set it off, but don’t indent it in the Lesson Plan.

In this lesson you will learn how to structure and format content for the web in the WordPress Content Editor for pages and posts. The editor uses a WYSIWYG (What You See Is What You Get) toolbar that is similar to word processing software and text editing applications. You don’t need to understand HTML code that is the standard for web content, as you can use the visual editor which creates and manages the underlying code for you. (Note that the WordPress editor does allow users to see and modify the actual HTML code for content, if desired.) You’ll also be able to add links, add images and media, and insert symbols and special characters to web content.

Objectives

List objectives as actions that the student can do once they’ve finished the lesson. Present them in an unordered list, prefaced with the introductory text, “At the end of this lesson, you will be able to:”. List objectives as the completion of sentences that begin with the introductory text, with the first letter capitalized and a period at the end of each sentence.

Use action verbs; see Bloom’s Taxonomy of Action Verbs (PDF) as a reference. Avoid using words like “know,” “understand,” “be introduced to,” etc.

Correct
At the end of this lesson, you will be able to:

  • Identify the files required to make a theme.

Incorrect

  • Students will know the files required to make a theme.

Top ↑

Time Estimate Time Estimate

The time estimate is your best guess how long a training session will typically be for an instructor who is well prepared and efficient to present the material, allowing for exercises and questions. Don’t stress over this too much; the estimate will be refined when the Lesson Plan is tested after you finish it and a copy editor reviews it.

Format the estimate as numbers and units in plain text with no punctuation:

30 minutes

Top ↑

Prerequisite Skills Prerequisite Skills

Prerequisite skills is a list of skills students require to learn and understand the material in the lesson plan. Present them in an unordered list. Preface the list of skills with the introductory text, “You will be better equipped to work through this lesson if you have experience in and familiarity with:”. List skills as phrases, not sentences, and don’t include a period at the end of each item. Capitalize the first letter of each phrase.

Correct
You will be better equipped to work through this lesson if you have experience in and familiarity with:

  • Editing files with a text editor

Incorrect

  • editing files with a text editor.

Top ↑

Teaching Materials Teaching Materials

Teaching materials is a list of everything that the instructor will need to teach the lesson plan. Present them as links in an unordered list. Do not place introductory text before the list of assets. List materials as phrases, not sentences. Capitalize the first letter of each phrase, as well as the formal titles of any themes, products, etc. Links to materials should open in a new tab and should include the title attribute within each link. If there are no required assets, please list “None.”

Correct

Incorrect

Top ↑

Readiness Questions Readiness Questions

Readiness questions is a list of evaluation questions for students to see if they have the skills necessary to learn and understand the lesson. You can use these as pre-screening questions on Meetup. Present them in an unordered list. Do not include introductory text before the list of questions. Write the items as questions and use a question mark at the end of each sentence. Capitalize the first letter of each question.

Correct

  • Do you have at least a basic knowledge of HTML/CSS?

Incorrect

  • you have at least a basic knowledge of HTML/CSS

Top ↑

Teaching Strategies Teaching Strategies

Teaching strategies is a list of suggestions and tips that help the instructor present the material in a meaningful way for students, increasing the chances for success for students. Present these in an unordered list. Do not include introductory text before the list of strategies. Write the items in the form [Applicable Area of Lesson]:[strategy] as phrases with no punctuation at the end.

Correct

  • Lecture: talk about the importance of properly formatted content
  • Demonstration: display the content editor toolbar and show it in action by hovering over each button and demonstrating its use
  • Exercises: have students practice on their own WordPress Post using the toolbar buttons to format content

Incorrect

  • During the lecture, talk about the importance of properly formatted content.
  • When performing a demonstration, display the content editor toolbar and show it in action by hovering over each button and demonstrating its use.
  • Have students practice on their own WordPress Post using the toolbar buttons to format content in the exercises.

Top ↑

Teacher Notes Teacher Notes

Teacher notes is list of any handy tips or information for the instructor, basically any other information that doesn’t fit anywhere else in the structure of the lesson plan. Present the notes in an unordered list. There should not be introductory text before the list of notes. Write the Notes in full sentences with the first letter capitalized and a period at the end of each sentence.

Add a final list item to indicate which version of WordPress that you built the lesson plan with. This will make it easier over time to maintain the lesson plan as WordPress evolves. Each time you review or update the lesson plan, particularly when updating screen captures, update the WordPress version number.

Note: Previously the Style Guide included the time estimate here, but now that is a separate item in the lesson plan structure.

Correct

  • The preferred answers to the screening questions is “yes.” Participants who reply “no” to all the questions may not be ready for this lesson.
  • This Lesson Plan is built using WordPress version 4.9.7.

Incorrect

  • preferred answers to the screening questions are “yes;” participants who reply “no” to all 4 questions may not be ready

Top ↑

Lesson Overview Lesson Overview

The Lesson Overview section should include an overall plan for the lesson, giving a suggested flow of how the training session should proceed. Present the items as an unordered list without introductory text. Capitalize the first letter of each item and do not include a period at the end.

A typical Lesson Overview might look like this, describing each major section of the training session:

  • Lecture on the need for proper formatting of web content
  • Demonstrate each of the toolbar buttons by displaying the content editor and showing how each button is used
  • Have students do the exercises on formatting content using the buttons in the toolbar

Top ↑

Exercises Exercises

Exercises are short or specific activities that test students’ understanding and help them practice certain components of the lesson. They should not be fully scripted exercises, but rather something that you would do on your own. For example, you can create an exercise based on one step of the hands-on walkthrough.

Include the exercise name as the title using the strong tag to designate the task for each exercise. Questions about each exercise should be presented in an unordered list. Questions should be written as questions and use a question mark at the end of each sentence. The first letter of each question should be capitalized. If there are no questions related to an exercise, then the exercises should be presented as an ordered list. Include introductory text as appropriate.

The following is one example of a single exercise in a Lesson Plan; a typical Lesson Plan might have several exercises:

Add Headings to a Blog Post

Using either lorem ipsum text or existing copy, have students

  1. Switch between Visual and Text modes.
  2. Add a variety of headings within a blog post. (Remember that Heading 1 is for the title of the blog post, so students should use Headings 2-6 inside their posts.)
  3. Apply bold and italic formatting to text.
  4. Add a link to an external webpage.
  5. Change the color of some text.
  6. Make a paragraph a blockquote.
  7. Add a special character to their text.
  8. Right-align a paragraph.

Top ↑

Differentiation Strategies Differentiation Strategies

Differentiation strategies provide ideas about how to accommodate different learning styles and speeds. Present these as an unordered list with no introductory text. Capitalize the first letter of each item and do not include a period at the end.

Sample

  • Have more experienced students help less experienced students
  • Have a spare website or computer available in case the student is having trouble accessing WordPress

Top ↑

Assessment Assessment

Assessment questions is a quiz that students can use to evaluate their retention of the material presented and emphasize important points. Using the strong tag around each question. Write each item as a question and use a question mark at the end of each sentence. Capitalize the first letter of each question.

List possible answers to questions in an ordered list. Answers can be phrases, sentences, code samples, etc. If the answer is a phrase or sentence, then the first letter of each answer should be capitalized.

Include the correct answer after the ordered list, with the strong tag around “Answer”. It is acceptable to have multiple possible answers comprise the complete answer.

Correct formatting for a single quiz question is as follows:

When developing for WordPress, what files should you never edit?

  1. Core WordPress files
  2. Plugin files
  3. Theme files
  4. All of the above

Answer: 4. All of the above

Top ↑

Additional Resources Additional Resources

Additional resources is an optional section which contains a list of resources that an instructor can use to get more information on the topic. Include the title or name of each resource with a link to it, as well as a short description of the resource. The link should open the page or other resource in a new browser tab. It is particularly useful to include links to relevant sections of the WordPress Codex here.

An example of an additional resource is:

  • Child Themes in the WordPress Codex includes a detailed description of the reasons to use a child theme and how to create them.

Top ↑

Hands-on Walkthrough Hands-on Walkthrough

The hands-on walkthrough provides a script, with screenshots and live demo instructions, that the instructor can use in a live classroom/workshop setting. This doesn’t necessarily need to be a complete script for an entire training session based on the Lesson Plan, but it can be. Or it can provide a suggested way to present the trickier or more difficult sections of a Lesson Plan.

Present the walkthrough in a conversational tone. Split the content into logical sections, using <h3> heading tags to designate headers. Insert <hr> rules to separate each section. Use <h4> tags to designate subheaders within sections.

Otherwise, present the material in the best manner you see fit for the content.


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]