Beth Soderberg 2:13 am on February 8, 2016
Tags: procedures ( 35 )

Common Styling Issues in Lesson Plans

In last week’s team meeting, I brought up a few common styling issues that copy editors have noticed while editing lesson plans. As promised, I’m expanding that list here. For more details on many of the items referenced in this list, please refer to the style guide.

Issues we’ve seen frequently include:

Lots of different kinds of quiz formatting. The quiz formatting is outlined in the style guide, so take a look at that when writing out quiz questions.
Random horizontal rules. We don’t need these to separate major sections (e.g. “Teacher Notes” from the “Hands-On Walkthrough”), but watch out for them because they are included in some plan drafts that were created a long time ago. Please DO use horizontal rules if they make sense to separate sections of content within the hands-on walkthrough section.
Capitalizing WordPress specific terms and phrases like “Posts,” for example. Unless a word is a proper noun in general, we don’t need to capitalize it.
Absence of punctuation. Sentences should always end with the appropriate punctuation!
Misspelling of WordPress. WordPress has a capital “P” and should never ever be spelled with a lower case “p.”
Inclusion of random notes. Once you’re done with your lesson plan, make sure you’ve deleted any notes you wrote to yourself as you were working!
Absent quizzes. Be sure to include 1-3 quiz questions for your lesson plan. If you’re not sure what the questions should be, that’s ok. In this case, flag that the quizzes are absent before sending the plan to copyediting.
Absent exercises. Be sure to include an exercise that would take approximately 5-10 minutes to accomplish. As with quizzes, if you’re not sure what the exercise should be, flag that an exercise is absent before sending the plan to copyediting.

We’ll be using this list to create a checklist for lesson plan authors to go through before submitting their plans for copyediting and for copy editors to use while editing, so please list any additional items you’ve noticed in the comments!

#procedures

Courtney Engle Robertson 2:26 am on February 8, 2016

Also I’ve found a few plans that weren’t using the approved filler content as outlined in the style guide. Theme Unit Test Data and PlaceKitten.

I am still hoping to have some clarity on 3rd party plugins approval when just needing to demonstrate how to download and use a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party for a widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user., or other similar purpose. The undocumented policy has been to only stick to plugins made by the user @wordpressdotorg. I’d like to see this documented within the style guide.
- bethsoderberg 3:00 am on February 8, 2016
  The style guide currently states the following regarding .org:
  
  The Make WordPress Training lesson plans are a project of 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/. 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.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/
  - Paid services and resources, including plugins and themes
  - Courtney Engle Robertson 12:48 pm on February 8, 2016
    
    No mention of the no 3rd party .org repo plugins. Hmmmm
Julie Kuehl 5:48 pm on February 23, 2016

Keep an eye out for the word “module.” It was a term we were using early on, but it should be replaced by “lesson.”
- bethsoderberg 5:58 pm on February 23, 2016
  
  I noticed that during the meeting too! It’s still hiding places 🙁
Julie Kuehl 7:21 pm on February 23, 2016

Somewhere along the way we should be cross-checking with what the Docs team is doing and what is out on the Codex / HelpHub / Developer resources. Not sure if that is a copyeditor’s duty or more on the author’s shoulders.
- Courtney Engle Robertson 3:11 pm on February 24, 2016
  
  I am doing this as I find the resources from Codex/Docs currently for a reference for students in my class. It helps to address multiple learning styles by instruction/demonstration reinforced with anything text-based from Docs/Codex, and any relevant video resources from WPTV in my plans.
  - Julie Kuehl 3:55 pm on February 24, 2016
    
    Should we add a “Related WordPress Resources” section?
    - Courtney Engle Robertson 7:05 pm on February 29, 2016
      
      That might be good. I’ve been sending it in with my testing feedback for now under additional comments. I suppose when whomever reviews my tests, they could add the additional WP resources. I am trying to keep it within the .org ecosystem for my feedback, though I did just show students a video today from WP Beginner related very well to Installing Plugins.
Julie Kuehl 1:30 pm on February 25, 2016

I wasn’t going to raise this, but because I think this makes things clearer for students…

“Capitalizing WordPress specific terms and phrases like “Posts,” for example. Unless a word is a proper noun in general, we don’t need to capitalize it.”

I’m going to argue that at times they are proper nouns. It’s similar to how The White House is a proper noun for a white house. When we refer to specific elements of WordPress, such as Pages and Posts, that is their unique, proper name, I believe that this makes sense and helps make things clearer for students: “To create a new page, look for Pages in the left-hand menu.” To be clear, this does not mean every time the word “pages” shows up it should be capitalized.
skarjune 5:03 pm on March 29, 2016

As Julie indicates, some WordPress terms should be considered Proper Nouns in some cases. The use of capitalization, strong (bold), and quotation marks for emphasis has variation and inconsistencies. “Posts” and “Pages” are a good example: they would be best capitalized when referring to the Dashboard menu and admin sections, where they are capitalized. Of course, most cases in passing should not be capitalized. More of a context, than Proper Noun call.

Filenames are handled in various ways, while Style Guide indicates using the tag.
The "Hands-on Walkthrough" gives some guides for general layout with & to break down into sections, but this is not used much. Instead, some use for subheads and within paragraphs to break down items. Some use lists to breakdown items, but not clarified by the Style Guide. Finally, more use of short codes like [info] would be helpful to highlight important concepts, tips, gotcha alerts, would be helpful. It's difficult to sort these out when drafting, but should be a copyediting concern. The editor needs both refer to the Style Guide and wear a Reader hat. Perhaps the Style Guide needs a more thorough discussion on these along with more examples.
- skarjune 5:05 pm on March 29, 2016
  
  OOPs, I didn’t realize comments used full HTMLHTML 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.! that was a CODE tag up there…and not sure what else happened. YUK!
bethsoderberg 1:20 am on March 30, 2016
I disagree on the proper noun thing, though in surveying the WordPress universe (looking at random pages in the codex and developer documentation) I’m noticing that throughout the universe people use WP terms as proper nouns inconsistently. It’s not everywhere, but it is some places. My preference is to have some other indicator (bolding maybe? quotes?) to indicate that the word is a special WordPress word. From a grammar standpoint, I feel weird about the proper noun thing. Every time I see it it I think it looks incorrect and makes the lessons appear to be less authoritative. The need we’re describing here reminds me of how terms were bolded in my social studies textbooks in elementary school to indicate that they were vocabulary words. Maybe we could do something similar to fill the need that is being described here?

Also, totally unrelatedly, when the style guide was first written it was based off of what I think docs was using at the time. I dug up these style resources from elsewhere in the WP world so that we can cross-reference what we have to what is established elsewhere:
- Codex Guidelines: https://codex.wordpress.org/Codex:Guidelines
- Developer Documentation Style Guide: https://developer.wordpress.com/themes/documentation-style-guide/
- Handbooks Style Guide: https://make.wordpress.org/docs/handbook/developer-resources/handbooks/handbooks-style-and-formatting-guide/
skarjune 9:49 pm on April 4, 2016

I like the notion of vocabulary words, as indeed the terms post and page are not Proper Nouns, per se. Still, they don’t need particular formatting like bold in all cases. However, when referring to a Dashboard menu item like Posts or an admin page with the title Posts, it’s capitalized in those contexts, so that references to those particular contexts should also be capitalized.

Thanks for the references. I’ll review those. Less concerned about what’s right, more concerned about clarity and consistency so the UXUX UX is an acronym for User Experience - the way the user uses the UI. Think ‘what they are doing’ and less about how they do it. effectively matches key words to their use in training situations. This would be a straightforward copyedit review of lesson plans, if cleared up somehow.

Welcome

Meetings (Calendar)

Common Styling Issues in Lesson Plans

&

Welcome

Meetings (Calendar)

Share this: