Style Guide

Purpose: This style guide was created to promote a more uniform organization and voice throughout the TFResource wiki. The intention is not to create burdens that discourage content contribution, but rather to guide the drafting of content so that authors can focus more on the content and spend less time worrying about page organization, intended audience, and tone.

Intended audience: Since modelers frequently collaborate with planners, the wiki should be accessible to both groups of people. This will also benefit modelers and students newer to the field. Please make a concerted effort to write with these groups in mind.

# Page Title

  • Carefully consider whether a new page is necessary. Does your new content better fit onto an existing page?
  • Make sure that page does not already exist under a similar or different name (search for applicable or shortened keywords).
  • All page titles should be uppercase.
  • Keep page titles as short as possible.
  • Make them clear - the page title should give a clear indication of the page content
  • Use consistent titles that go well with existing page titles.

# Organization and Structure

  • Start with introduction/abstract to set the context; list suggested prerequisites
  • Use subheadings/subsections (rule of thumb is 2-3 paragraphs per subsection)
  • The page should not be too long; consider subpages if page is significantly longer than other pages (rule of thumb is 3 scrolls)

# Language and Tone

  • Professional/Formal
  • Free of colloquialism (avoid informal/conversational style). See here for examples
  • Friendly (less academic, and not negative about differing approaches)
  • Avoid first person
  • Concise text (to the point)
  • Limit use of abbreviations. If you do use common acronyms (like TAZ and ABM), define them in the acronym list as follows:
    • Add an acronym to the list at .vuepress/public/acronyms.csv
    • Call out the acronym in the page text with double equal signs, e.g. <span><div class="hint--html hint--top hint--hoverable"> TRB <div class="hint__content"> <h3>TRB</h3> <p>Transportation Research Board</p><p class="hint__tiny__left"><a href="">More info</a></p> <p class="hint__tiny">See the full <a href="/topics/glossary">TFR Glossary</a></p> </div></div></span> will pull up the definition of the TRB acronym
    • Example of doing this is here

# Formatting

  • Graphics
    • Use vector images (SVG format) if possible
    • If you use a raster image:
      • Choose minimum resolution of 72 ppi
      • Avoid large file sizes
        • Suggested maximum size of 10MB
        • Check the image dimensions (avoid images that are much larger than the intended space on the wiki page)
      • Choose PNG or JPG format (JPGs are lossy, however)
  • Links/cross-links
    • Cross-links: When talking about a topic/term, link to that page from the text.
    • Use cross-links as often as possible on all pages throughout the wiki. This will make navigating much easier and will guide people to the important pages and topics the text is talking about.
    • Spell the "link text" in the grammatically correct way of your surrounding sentence (including upper- or lowercase).

# Content

  • No duplication of content. Explain a topic on one page where it fits best. If you need to refer to that topic on another page, link back to the original page, do not recreate explanations/descriptions/facts twice. This would turn maintenance into a nightmare and invite inconsistency/contradiction. And it is plain bad practice.
  • Do not copy over text from Wikipedia or other similar web resources. If there is relevant and useful information, provide a link under the section "See also" at the end of the page.
  • Respect all copyright and other intellectual property laws. This includes academic papers published in other venues (such as TRB) and their abstracts.
  • Try to be write objectively and avoid adding biases and opinions
  • Give credit where it is due (plagiarism)

# Example Pages

If you are looking for an example page that exemplifies the organization, formatting, and tone required by this style guide, see the following page: