The Training team is reviewing the status of the Lesson Plan Style Guide and how it’s used with lesson plans, and considering if a Glossary might be added. During the January 10, 2017 meeting, some concerns were raised:
@donkiely was concerned about grammar usage, such as while/although
@estes.chris mentioned Oxford commas (serial commas)
@pbarthmaier mentioned post vs Post and page vs Page
@juliekuehl said that “We’ve avoided using one of the major style guides and have worked out our own.”
@chanthaboune indicated that @bethsoderberg keeps the styleguide current.
@donkiely has noticed: I’ve spotted several places where existing lessons and placeholders don’t comply with the style guide.”
@donkiely asked “So the main question is, too heavy handed? Or, too subtle to worry about?”
@chanthaboune said: “I’m of two minds about it. On the one hand, if it’s going to help with understanding, that’s important. But on the other, these aren’t word-for-word scripts in many cases. So getting picky for stylistic reasons seems to be a forest for the trees situation.”
The team agreed that some of these concerns are already covered in the Lesson Plan Style Guide. For example, the Grammar section details WordPress elements as regular nouns, not proper nouns, and the use of the Oxford comma before the final conjunction. The range of topics in the guide includes:
Content: Resources, Tone, Grammar
Structure: Description, Objectives, Prerequisite Skills, Assets, Screening Questions, Teacher Notes, Hands-on Walkthrough, Exercises, Quiz
Assets: Approved Themes, Images, Screenshots, Placeholders, Naming Conventions, Content Colors,
Formatting: Basic Conventions, Emphasized Text, Code Examples,
Issues
Accessibility 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): General Items, Links, Images, Multimedia, Abbreviations
The guide references additional resources for more detailed guidelines:
- Anatomy of a Lesson Plan (Training companion)
- Bloom Bloom's Taxonomy is a way of writing lesson plan objectives using specific words so that the objectives can be measured. See https://make.wordpress.org/training/handbook/guidelines/blooms-taxonomy/ for more details.’s Taxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies. (external PDF)
- Approved Themes list of Twenty Twelve through Twenty Sixteen
- Theme Unit Test Data (import file from Automattic)
- lipsum.com (Lorem Ipsum generator)
- Placekitten (placeholder images)
- W3C The World Wide Web Consortium (W3C) is an international community where Member organizations, a full-time staff, and the public work together to develop Web standards.https://www.w3.org/. HTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. and CSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. Recommendations (separate content from styling)
- W3C’s Web Content Accessibility Guidelines
In general the team thinks that the Lesson Plan Style Guide is complete, may need some minor revisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision. and review, and that the main issue is that copyediting should check for consistency with both the guide and the Anatomy of a Lesson Plan reference.
Some areas for review are the use of assets, images, screenshots, and sample content, as this is where the context of various lesson plans can enter gray areas and they may add constraints for copyediting or updating the material.
While the team maintains a Training style guide, an external style guide might considered as an additional external reference. However, all major style guides, such as Chicago Manual of Style and Associated Press Stylebook, are proprietary and fee-based for online use. As an alternative, MailChimp has a MailChimp Content Style Guide available under a Creative Commons license and publicly available on GitHub GitHub 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/:
This is our company style guide. It helps us write clear and consistent content across teams and channels. Please use it as a reference when you’re writing for MailChimp.
This guide goes beyond basic grammar and style points. It’s not traditional in format or content. We break a number of grammar rules for clarity, practicality, or preference.
We invite you to use and adapt this style guide as you see fit. It’s completely public and available under a Creative Commons Attribution-NonCommercial 4.0 International license. All we ask is that you credit MailChimp.
The team was divided about the need for a Glossary to accompany the existing resources, and whether or not we should reference an existing resource or build or own. There are two major WordPress glossaries available that could be referenced as resources:
WordPress Codex Glossary: This document is designed to offer definitions of various terms, exclusive to WordPress, that users may not be familiar with.
WordPress.com Learn Get Lingo: You’ve got a blog: huzzah! Whether you want to be a WordPress.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/ pro or just need to learn the basics, you’ve come to the right place.
The team suggested that Training inquire with the Docs team for information about how the Codex Glossary is maintained and used. At a recent meeting on January 10, 2017, the Docs team discussed creation of a new Glossary being performed by @normalize. Documentation Team Lead @kenshino suggested that the new format could use a Custom Post Type WordPress can hold and display many different types of content. A single item of such a content is generally called a post, although post is also a specific post type. Custom Post Types gives your site the ability to have templated posts, to simplify the concept. (CPT) for each glossary item, as they are short and can link to full Codex articles for more information. The Docs team is looking at how this would be implemented in the new Helphub.
