Lesson Plan Style Guide

The WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ Training Team’s style guidelines are a reference point to maintain consistency while developing new lesson plans and slides. In order to maintain consistency we ask that you please follow this style guide.

The Training Team lesson plans are part of the WordPress.org open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. project. As such, these lesson plans should not incorporate content that refers to or details elements of either WordPress.comWordPress.com An online implementation of WordPress code that lets you immediately access a new WordPress environment to publish your content. WordPress.com is a private company owned by Automattic that hosts the largest multisite in the world. This is arguably the best place to start blogging if you have never touched WordPress before. https://wordpress.com/ or paid services and resources (including plugins and themes) unless the Training Team has collectively decided that an exception makes sense.

In this guide you will find some spelling, punctuation and grammar guidelines. Following these guidelines will help keep all lesson plans consistent. These are guidelines and not rules. But we strive to be consistent to make our resources more usable. In addition to applying the spelling, punctuation, and grammar guidelines consistently it’s important to use terms and vocabulary consistently so as not to confuse people.

When describing something, be precise and specific. Wherever possible, it’s best to both show and tell. Often a simple picture can convey information that can be both hard to explain and understand using a complicated description.

Language and Spelling Language and Spelling

US English is the default language of the WordPress.org Training Team resources. If you wish to write lesson plans and English is not your first language, don’t panic! All lesson plans are reviewed by a copy editor as part of our process and they can help with that. On the other hand, if you are contributing by being a copy editor, you also don’t need to panic. There are lots of helpful and friendly people on the SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. #training channel who will happily answer your questions.

All resources should use standardized English grammar and American English spelling. You can find more information on suitable English grammar and spellings in the WordPress.org Documentation Team’s Grammar Guide. And if any terms are unfamiliar to you, there is a WordPress Glossary available from the Marketing Team.

This guide is for English-language resources. If you are not writing in English, or wish to translate a resource from English to another language, please also refer to the guidelines for your locale and try to keep the content and style as close to the original as possible.

Top ↑

AccessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) Accessibility

Making our materials accessible to as many people as possible is a guiding principle of the team. As you are writing lesson plans and other resources you should include accessible elements were possible.

Where possible, follow the W3C’s Web Content Accessibility Guidelines. These guidelines are organized around the four following principles.

  • Information and user interface components must be presentable to users in ways they can perceive.
  • User interface components and navigation must be operable.
  • Information and the operation of user interface must be understandable.
  • Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies.

Accessibility suggestions and guidelines can be found in the relevant sections throughout this guide.

Top ↑

Introduction to the Repo Structure and Lesson Plan Template Introduction to the Repo Structure and Lesson Plan Template

In order to maintain consistency and allow for automation, all lesson plans follow the same structure. The current, definitive structure is found at the Repo Structure and Lesson Plan Template repository in the Training Team’s GitHub organization. This repository functions as a template for starting a new lesson plans. In addition, the template includes a description of the purpose of each section and each section’s preferred structure.

Please use the lesson plan template in order to ensure that your new, or revised, lesson plan contains all the sections in the required structure. If you are revising a lesson plan that does not follow the template structure, please adjust the lesson to fit the current format. If you are unsure of how to do this, please leave a comment in the lesson plan’s TrelloTrello Project management system using the concepts of boards and cards to organize tasks in a sane way. This is what the make.wordpress.com/marketing team uses for example: https://trello.com/b/8UGHVBu8/wp-marketing. card or file an issue in its GitHubGitHub GitHub is a website that offers online implementation of git repositories that can can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ repo to ask for help in making the necessary adjustments.

Before you can get started you need to create a GitHub account, then all you need to do is get a copy of the lesson plan you want to work on by forking the repo. Instructions on how to do this can be found in the Using GitHub guide.

You can now edit your repository as required. When committing changes to your repository, try to provide a descriptive commit message to explain what changes you have made. This makes it easier to check your changes when you submit a pull request. Instructions on how to create a pull request can also be found in the Using GitHub guide.

Top ↑

Filing Issues in GitHub Filing Issues in GitHub

As you work on lesson plans, and the associated training resources, you may have to temporarily or permanently put the project to one side, leaving it in an unfinished state. If you encounter this situation please submit a pull request with your work (in whatever state) or file issues in GitHub so either you, or someone else, can quickly pick up the project again at a later date. In order to do this please use the issues tab in GitHub.

Go to the repositories home page. You normally open a repository on the ‘<>Code’ tab.

Next to the ‘<>Code’ tab you should see the ‘Issues’ tab. If you don’t see the issues tab, don’t worry, sometimes when you fork a repository this tab is not automatically available. Instructions on how to make the ‘Issues’ tab available are below.

To make the issues tab available, go to the ‘Settings’ tab.

Scroll down to the ‘Features’ section, you should see an unchecked checkbox next to the ‘Issues’ feature. Check this box and the ‘Issues’ tab will appear next to the ‘<>Code’ tab, as shown above.

To file and issue go to the ‘Issues’ tab and click on the ‘New issue’ button.

Give your new issue a descriptive title and describe the issue in detail in the comments box. Submit your issue and it will appear in the repo’s as well as the team’s issue list.

To add additional comments or close the issue when it is completed or no longer needed, open the issue via the ‘Issues’ tab. By clicking on the issue’s title you will be given the options to add a new comment or close the issue.

Once you have filed the issue, if you intended to return the the repository later you may just leave it as is is until you can return to it. But if you will no longer be able to work on the repository, please contact a member of the training team and they will arrange to pull your unfinished work into the team’s repository so that your work is not lost and the lesson plan can be reassigned to another contributor.

Top ↑

Content Content

Punctuation Punctuation

Always capitalize WordPress correctly.

Do not capitalize regular nouns. All WordPress elements as regular nouns: themes, post, or user.

Capitalise the names of pages, links, plugins and buttons: the Save button, or the Posts page.

Quotation marks (“) should be used only for direct quotes and the titles of documents and web pages.

Backticks (`) should be used to indicate a command, a file name, or something the user needs to type.

Use a colon (:) to introduce a list when it is preceded by a full sentence. Do not use a colon otherwise, even if you are introducing a bulleted list.

Use the Oxford comma, which means including the final comma before and, or or in a list: “apples, oranges, and bananas” and not “apple, oranges and bananas.”

Top ↑

Grammar Grammar

Grammar acts like a film director, building structure into a sentence to tell the reader what to focus on. Transitive grammar, or filmic word order, models the words on the page in the same sequence they would be experience on real life, making the sentence more immersive and easier to read or follow. Try to write in an informal but knowledgeable manner, the reader should feel that this is a friend explaining something clearly to them. Always write in the second person, using “you” not “we”, and addressing the reader as though they were sitting beside you. For instance, “navigate to the WordPress website and log into your WordPress admin screen.”

Avoid jargon, abbreviations, acronyms, or capitalizations. If you need to use any of these always write the full expanded or explained version the first time, followed by the shortened version in parenthesis (brackets). For example, “use the General Public License (GPLGPL GPL is an acronym for GNU Public License. It is the standard license WordPress uses for Open Source licensing https://wordpress.org/about/license/. The GPL is a ‘copyleft’ license https://www.gnu.org/licenses/copyleft.en.html. This means that derivative work can only be distributed under the same license terms. This is in distinction to permissive free software licenses, of which the BSD license and the MIT License are widely used examples.).”

Avoid slang words, cultural references, or idioms. The person reading may not be a native English speaker with a much difference experience than you and the meaning may not be clear to them.

Top ↑

Headings Headings

Use headings to identify the various sections within your lesson plan.

“Heading 1” is only be used for the lesson plans main title. Do not use this for any other headings.

“Heading 2” is used within the Repo Structure and Lesson Plan Template to identify the various section of the lesson plan. Please do not use this for any other headings. It is preceded by two hashes (##) in GitHub, such as “## Objectives”.

Headings 3, 4 and so on can be freely used as required within each lesson plan section to give the lesson plan structure and clearly identify subsections. “Heading 3” is preceded by three hashes (###), “Heading 4” is preceded by four hashes (####), and so on.

Top ↑

Emphasized Text in GitHub Emphasized Text in GitHub

Boldface, italics, and boldface italics can be used to emphasize words or indicate instructions. Do not underline words, or use all capitals. All links, and only links, should be underlined.

Use boldface to indicate instructions or when referring to menu items, such as Pages > Add New.

GitHub uses the following Markdown to embolden and/or italicize text.

  • To embolden text use **Text**
  • To italicize text use _Text_
  • To embolden and italicize use _**Text**_

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 as follows:

  • For informational messages, preface the paragraph with the following code: ![](https://raw.githubusercontent.com/wptrainingteam/contributor-resources/master/images/info.png)
  • For tips, preface the paragraph with: ![](https://raw.githubusercontent.com/wptrainingteam/contributor-resources/master/images/lightbulb.png)
  • To alert readers to important messages, preface the paragraph with: ![](https://raw.githubusercontent.com/wptrainingteam/contributor-resources/master/images/flag.png)
  • To warn readers about something that is particularly precarious, preface the paragraph with: ![](https://raw.githubusercontent.com/wptrainingteam/contributor-resources/master/images/dismiss.png)
  • To give the user ideas about the materials, 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)

Top ↑

Lesson Plan Elements Lesson Plan Elements

Top ↑

Approved Themes Approved Themes

When creating lesson plans or presenting lessons use one of the following approved themes:

Top ↑

On pages that contain multiple links ensure that the text used to describe each link is unique unless you are linking to the same resource in more than once place.

Use descriptive links instead of generic text, ensure the link text describes the resource you are pointing to, such as “you will be using the Twenty Nineteen theme” rather than “you will be the theme found here.”

Top ↑

Multimedia Multimedia

Make sure equivalent alternatives are available for audio/video content. This includes things such as captions for videos and alt="" descriptions for images.

Top ↑

Images and Screenshots Images and Screenshots

All images and screenshots should be saved in the /images folder in the GitHub repository and linked to from the lesson plan.

All filenames should be descriptive, all lowercase, and contain no spaces, such as kitten-in-basket.jpg.

Use descriptive alt="" text on all images, such as alt="page attributes section of edit page screen" and not alt="" or alt="screenshot" or other text which does not adequately describe the the content of the image.

All screenshots that show an operating system should be taken using a Mac computer. If you need help with this take a screenshot using your operating system and file an issue in GitHub to have it replaced. 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.

All images and screenshots should be full size. Do not include thumbnails that readers have to click on to see.

Annotations Annotations

Make all notations on images or screenshots using simple arrows and icons, and use red as the primary color for any annotations. If you need a secondary color for the annotations, blue is preferred, but any other color that provides good contrast is okay. Good contrast and readability is the number one concern. In general, keep notations to the minimum needed to make your point clear.

Top ↑

Placeholders Placeholders

Placeholder images should be sourced from Placeholder.com. This is done using a URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org that calls the image from the site using the size you prefer, such as:

<img src="https://via.placeholder.com/300x200">

where the 300 is the width and 200 is the height.

Top ↑

Sample Content Sample Content

If you need to include placeholder content in your demo theme, please download and use the Theme Review Team’s 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 a Lorem Ipsum generator to create this content.

Top ↑

Code Inspectors 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 Notes for Instructor portion of the lesson plan.

Top ↑

Code Examples Code Examples

Use standard Markdown syntax for each code language to wrap code samples. For instance, for JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/.:

```javascript 
var s = "JavaScript syntax highlighting"; alert(s); 
```

You can find a cheatsheet in the “Code and Syntax Highlighting” section of the Markdown Cheatsheet. For indentation use 4 spaces.

Top ↑

Preferred Colors for Diagrams and Charts Preferred Colors for Diagrams and Charts

When producing diagrams, charts, and where otherwise appropriate, use the following color palette: blue, orange, grey, and light blue. The coding for the specific shades is described below.

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

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