Dev-squad GitHubGitHubGitHub is a website that offers online implementation of git repositories that 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/ triage: Thursdays 07:00 UTC
The WordPress.orgWordPress.orgThe 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 SourceOpen 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.comAn 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.
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 SlackSlackSlack 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.
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.
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.
Inline links in content should open in the current window to ensure that there is no change of context.
AccessibilityAccessibilityAccessibility (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) suggestions and guidelines can be found in the relevant sections throughout this guide.
In order to maintain consistency and allow for automation, all lesson plans follow the same structure. A reusable blockBlockBlock is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. has been created for this in Learn WordPress. This reusable block is the template for starting a new lesson plan. In addition, the block includes a description of the purpose of each section and each section’s preferred structure.
Please use the reusable block 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 TrelloTrelloProject 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 ask for help in the #training Slack channel.
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 let us know in the #training Slack channel.
Note any issues against the Trello card so either you, or someone else, can quickly pick up the project again at a later date.
Give your new issue a descriptive title and describe the issue in detail in the comments box of the Trello card you are working on.
Once you have filed the issue, if you intended to return to the lesson plan later you may just leave it as it is until you can return to it. But if you will no longer be able to work on the lesson plan, please remove yourself as the owner of the Trello card and let us know in Slack so that it can be reassigned to another contributor.
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.
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.
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.
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.”
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 (GPLGPLGPL 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 different experience than you and the meaning may not be clear to them.
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 reusable Lesson Plan block to identify the various section of the lesson plan.
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.
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.
If you want to alert the user to something, there are a variety of blocks you can use for various purposes:
For informational messages, use the Info Callout block
For tips, use the Tip Callout block
To alert readers to important messages, use the Alert Callout block
To warn readers about something that is particularly precarious, use the Warning Callout block
To give the user ideas about the materials, use the Tip Callout block
For displaying code, use the Syntax Highlighter block
When creating lesson plans or presenting lessons you can use any of the default themes with an emphasis on representing the more recent versions where possible:
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 using the theme found here.”
Make sure equivalent alternatives are available for audio/video content. This includes things such as captions for videos and alt="" descriptions for images.
All images and screenshots should be saved in the /images folder in Learn WordPress 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 state the operating system used. Please note that the editorial team might update those screenshots.
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.
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.
Placeholder images should be sourced from Placeholder.com. This is done using a URLURLA 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:
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.
If you need to show a code inspector in your screenshot, please use Firefox’s or Chrome’s default code 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.
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.