PhysPort Recommendations »Style Guide

PhysPort Recommendations Style Guide

The goal of a PhysPort Expert Recommendation is to:

  • Answer a real question that physics faculty have
  • Use their own language
  • Make sense and feel satisfying to them
  • Draw on results of physics education research (PER)
  • Draw on collected informal wisdom of PER community
  • Support equity and inclusion in physics classrooms and departments

How can I achieve this goal?

Title

Big question that real physics faculty ask (e.g., “How can I facilitate my students working in groups?”)

Headings

  • Reader should be able to get an idea of the main point by skimming the headings
  • Use many headings and subheadings to break up text and outline main points
  • Headings should summarize what sections are about
  • Use questions, statements, or verb phrases in headings (use nouns and noun phrases sparingly)

Language

  • Use a conversational tone, like you’re talking to a colleague in the hall
  • Everything you write should answer a question your colleague actually has
  • Frame things in the language of your target audience (physics faculty)
  • Use “I” and “my” in questions in titles and headings 
  • Use “you” and “your” in the answers to questions
  • Use “we” and “our” to refer to Expert Recommendation author or PhysPort
  • Use active voice most of the time
  • Don’t use PER jargon (or any other jargon)
  • Never use a big word when you can use a small word to say the same thing (e.g.,“use” not “utilize”)
  • Ask the reader questions
  • Give concrete examples from familiar physics classroom contexts
  • Give concrete suggestions

Values

Provide recommendations that:

  • Are based on research on and/or a process of regular reflection on, assessment of, and improvement of teaching
  • Support equity and inclusion in physics classrooms and departments
  • Recognize all students, faculty, staff, administrators, and members of the public as valuable and capable; seek to identify and build on their strengths; and do not characterize them in terms of their deficits
  • Recognize a variety of different perspectives within the physics education and physics education research community

Length

  • An expert recommendation should be an appropriate length to give a reader an overview of the topic without overwhelming them.
  • In most cases, an expert recommendation should be approximately 1-2 pages in length. Longer articles may be appropriate for more complex topics.

Visuals

  • Include at least one picture that we can use as the thumbnail for your expert recommendation
  • Use pictures, diagrams, and graphs whenever possible to help your reader visualize, but also provide alternate text for these.
  • Turn sentences into more visual forms like lists and tables, e.g., use bulleted lists to present a series of parallel ideas
  • Break text into small chunks (keep paragraphs and sentences short)
  • Use bold for key words

Research and resources

  • Cite research to back up your assertions where possible (see below for how to format references)
  • Distinguish between suggestions that are well-supported by research and those that are based on experience
  • Include lots of links to outside resources, links should be descriptive phrases, not “here” or html

Nitpicky formatting things

  • Write your draft in Word or Google docs, then once it’s polished, we’ll insert it into our web interface.
  • Use heading styles rather than manually making text bigger/bolder for headings.
  • Use single spaces, not double spaces, between sentences.
  • Do not insert extra line breaks between paragraphs. Our system will automatically create appropriate spacing between paragraphs.

Formatting references

  • Provide a list of references and include for each reference the author(s), year of publication, and DOI (preferred) or website (if DOI is not available). Our system automatically formats references from the DOI, so these references do not need to be in any particular format or order.
  • Refer to references in the body with "(Author last name date)". Our system automatically links in-text citations to the reference list, so you don't need to worry about linking them yourself. For this process to work, intext citations must be formatted using the following rules. Don't worry too much about getting this formatting exactly right; we can go in and make adjustments during the copyediting stage.
    • 1 author: (Author last name date). Example: “Assigning a reporter ensures that those less likely to volunteer will have opportunities to practice sharing their ideas (Tanner 2013).”
    • 2 authors: (First author last name and second author last name date). Example: “Don’t use a task that is overly challenging, especially at the start of the course, as it can reinforce student fears of incompetence (Gaffney and Whitaker 2015).”
    • 3 authors: (First author's last name, second author's last name, and third author's last name date). Example: “To engage in active learning, students need to feel comfortable taking risks in the classroom and then have those risks rewarded (Penuel, Abrahamson, and Roschelle 2006).”
    • 4+ authors: (First author last name et al. date). Example: “With a clear, consistent routine, students will know what is expected of them and feel more comfortable (Tharayil et al. 2018).”
    • For multiple references, separate each reference using a semicolon. Example: “Engagement has three primary aspects (Engle and Conant 2002; Fredricks, Blumenfeld, and Paris 2004; Chapman 2003; DeMonbrun et al. 2017; Nguyen et al. 2021).”
  • Some common pitfalls to avoid:
    • If there are three authors, put commas between the names of each author, and use an oxford comma before “and”.
    • Do not put a comma or any other punctuation between the author and the year.
    • “et al.” ends with a period but does not include any other punctuation.
    • Use only semicolons between references.
  • Note that any citations that do not follow this exact format will need to be linked by hand. This may be necessary in some cases such as:
    • If you need to put the name in the text of the sentence, e.g., “According to Seidel and Tanner (2013), students may not know the value of active learning.” However, in this case, consider instead saying “Students may not know the value of active learning (Seidel and Tanner 2013).”
    • If you are citing more than one reference with the same author(s) and year, e.g., “We extensively test and evaluate each simulation to ensure educational effectiveness (Adams et al. 2008a; Adams et al. 2008b).”

Examples

Read examples of Expert Recommendations on PhysPort.