On this page:

  • Writing Guidelines
  • Terminology to Standardize
  • Figures
  • Tables
  • Abbreviations, Capitalization and General Terminology
  • Punctuation
  • Numerals
  • Hyphenating
  • Lists
  • Bibliography
  • Common Errors
  • Issues to fix

 Writing Guidelines

  1. Use American spelling: e.g., ionization (not ionisation), flavor (not flavour) and so on.
  2. Use active voice as much as possible. Avoid writing in passive voice.
  3. Avoid use of first person (e.g., I and we)
  4. Use tables and figures to highlight content. It increases readability. 
  5. Use consistent terminology. (If you call it a spade here, call it a spade there.)
  6. Expand abbreviations at first occurrence.
  7. Do not split infinitives. E.g., "to choose carefully" is good, but "to carefully choose" is bad.
  8. In paragraphs that enumerate lists of things, use bullet or numbered lists ('itemize' or 'enumerate' in LaTeX) unless it seems overblown; otherwise use open-close parens with number, e.g., (1) blah, (2) blahh, ... and (n) blahhhhh. I.e. do not use 1), 2), or (a), (b)... etc.
  9. (Word-based volumes) Use prescribed paragraph and character tags. Do not bastardize existing paragraph and character tags to create new ones that do not belong in a template unless there is a special need to do so. 

  10. Technical sections of a design document:
    1. Begin with: The scope of the (name of system) includes the design,procurement, fabrication, testing, delivery and installation (or whatever it includes) of all the systems and components that comprise it: (follow with a list)
    2. This should be followed by a list of (major) requirements that the system must satisfy.
    3. Check this against the requirements documentation .
    4. The section should clearly indicate how each requirement is met.
    5. The section should outline the system to appropriate level of detail.
  11. Referring to CERN prototype detectors, please use: LaTeX
    • \cernsingleproto
    • \cerndualproto

Terminology to Standardize

Overall

Misc:

  • American spellings
  • antiwhatever not anti-whatever (e.g., antineutrino, antimatter...)
  • "muon antineutrino" not "antimuon neutrino"
  • Minimum ionizing particle: MIP, mip or m.i.p.?
  • beamline not "beam line" or beam-line
  • "Detector" should be used for the entire ND or FD, not for a module
  • can use ND, FD for near and far detector
  • Use Far Detector or Near Detector with initial caps when you refer to the name of a building such as Far Detector Hall or Near Detector Hall. Conversly, do not capitalize facility as it is a common noun, unless the word facility is in the name of the structure.
  • Also, capitalization in headings and captions should be minimized.
  • "Detector Module" = any 10-kt portion
  • Reference FD is 40 kt.
  • For non-reference design, call it "alternative" not "alternate"
  • Do we want to say "a 10-kt TPC?" I prefer "a TPC in a 10-kt module"
  • Use "dual-phase" not "double-phase"
  • (See more under "Hyphenating" below)
  • readout, not read-out
  • offline, not off-line
  • co-spokespersons not co-spokespeople

  • LBNF and/or DUNE: When to use which or both?
  • DUNE – collaboration, experiment, detectors, also "DUNE Project" to build detectors
  • LBNF — facility enabling the experiment, "LBNF Project" to build the facility
  • LBNF/DUNE (order not always clear...) — DOE-level project that encompasses facility+detectors

More on LBNF and DUNE (per Stephen's comments)

  • LBNF = the facility: the set of beamline, near and far site CF and cryostat/cryogenics systems
  • LBNF Project = the activity requiring funding, management and organization that is dedicated to constructing the facility
  • LBNF Project Office = the set of people managing the Project that report to the funding agencies
  • LBNF Project participants (awkward?) = everyone working on the Project
  • LBNF Organization = ? Maybe should be LBNF Project Organization = org structure of Proj Office + participants

Figures

See Graphics Guidelines

Figure captions go below the figure. All figures require a reference to them within the text. The reference should read "Figure n.m" as in "see Figure 3.4."  Capital F, full word (i.e., not "Fig 3.4")

LaTeX authors: use the "cdrfigure" environment as described in https://github.com/DUNE/document-guidance and on LaTeX Instructions, Quick References.

Tables

Table captions go above the table. All tables require a reference to them within the text. The reference should read "Table n.m" as in "see Table 3.4."  Capital T, full word (i.e., not "Tab 3.4")

Tables should look similar in style to this (colors are still TBD):

  

sample-table-format.png 

LaTeX authors: use the "cdrtable" environment as described in https://github.com/DUNE/document-guidance and on LaTeX Instructions, Quick References.

Word authors:

  1. Use the Insert Table option in Word and select the desired columns and rows.
  2. Heading Row:Bold body text (Calibri 11), Select Dark Blue, text 2, lighter 80% from the color palette.
  3. Right click on the header row, select Table Properties>Row and select Repeat as header row at top of each page.
  4. Use Calibri size 10 font for body and size 11 for heading. Few variations may exist for tables that are graphics etc.
  5. Left justify tables.

Abbreviations, Capitalization and General Terminology

  1. Expand all abbreviations at first occurence and use the following format: Conceptual Design Report (CDR)
  2. Use primary, secondary "objectives" (not goals)
  3.  U.S. not US
  4. Ph.D not PhD.
  5. Use Nature capitalized as in "Nature is kind" but not in "the nature of the problem"
  6.  "a" liquid argon TPC, and also "a" LArTPC (i.e., a 'lar' TPC not an 'ell-ay-are-TPC') 
  7. Do not pluralize abbreviations using an apostrophe (‘) following the abbreviation. Example: CDRs are important design documents. Not CDR's. Exception: Pluralize possessive case or when the abreviation or acronym has internal periods. (Refer to the Style Guide.)
  8. kt not kton ("kiloton" only when used as in "a kiloton of LAr is...") 
  9. Use space between number and unit: e.g., 1,300 km not 1,300km (sometimes '1,300-km baseline') LaTeX: follow guidance-document on GitHub
  10. (LaTeX) units outside of $...$ so they're not italicized.
  11. Use of “that” and “which.” Use “that" for restrictive clauses (clauses that cannot be removed without altering the meaning of the sentence). Use “which” for non-restrictive clauses (clauses that can be removed without altering the meaning of a sentence.) Tip: Use “which” in conjunction with a comma and check if that clause can be removed without changing the sense.

Punctuation

  1. Use of single quotation marks (') is non-standard. Use double quotes (") to set off special references. Better to use italics.
  2. Use nu sub e plural (and others) with apostrophe.
  3. Place commas and full stops (periods) within quotation marks. Colons and Semi colons go outside the quotation marks. Question marks, dashes/hyphens, and exclamation marks go inside or outside a sentence depending on where they belong in the sentence.
  4. Use of semi colons: Ensure the part following the semi colon is a complete sentence.

Numerals

  1. Generally, spell out numbers one through nine. Use numerals for 10 and above.
  2. Comma in numbers >1,000, e.g., 4,850
  3. When possible, avoid starting a sentence with a numeral.
  4. Use numerals when giving dimensions, weight, distance, etc., use numerals. Other usages that always use numerals, for example, are dollars ($1 billion, not $1,000,000,000), ratios, etc. Also tables often use numerals for everything.
  5. For example: seven 1-ton-rated-or-less pickups ... two vans (one cargo, one equipment)... one eight-passenger suburban ...
  6. In some cases you use numerals for ease of reading: There were 12 boys and 3 girls.”

Hyphenating

  1. Use dashes:  2 dashes together: -- in text for e.g.,  here we have x -- according to joe -- which does such and such (not great example, sorry!) (LaTex)
  2. Say antiwhatever not anti-whatever (e.g., antineutrino, antimatter...)
  3. Say "muon antineutrino" not "antimuon neutrino" 
  4. Use beamline not "beam line" or beam-line 
  5. Use world-class but worldwide   
  6. Use dash in double-beta decay, (and inverse-beta decay)
  7. I've been using a hyphen when first adjective modifies following adjective, not the noun. E.g. deep-underground location vs. located deep underground.
  8. Use 10-kt mass (with hyphen) vs. mass of 10 kt (without)
  9. May use "oxford commas" (e.g., "x, y, and z")
  10. High-resolution detector (with hyphen) vs. high resolution of the detector (without)

Exceptions

  • neutrino oscillation physics, muon neutrino BUT muon-neutrino beam
  • never between adverbs and adjectives (except for "well" as in "well-conceived"), e.g., fully realized configuration (however: full-scope configuration)   

Lists

  1. Use an ordered list (or numbered list) when the items in the list follow a certain order or sequence of events and not because the items in the list contain a fixed number.
  2. Use an unordered list (bullet list) when the items in the list do not follow any specific order.
  3. Use a stem sentence to introduce a list and write the stem in a complete sentence, wherever possible.
  4. Do not use “the following” as a noun in a stem sentence. Instead, use following as an adjective that qualifies a noun. Use a colon if “following” or “follows” is used. Use a period if “follows” or “following” is not used in the sentence.
  5. Avoid using the term list, listed, and so on. It is redundant. Avoid using “below” in stem sentences.
  6. Follow parallel construction in list sentences.
  7. Use the right punctuation. Use periods after complete sentences. Do not use periods after phrases or words. Avoid split sentences and punctuation.
  8. Use consistent capitalization. Initial cap all items. Initial cap the first word in a list if it is a sentences or phrase. Use lower case only for file names, and references that are strictly lower case.
  9. Use up to 2 sub-levels of lists.

           For examples, refer to the Style Guide.

Bibliography

LaTeX volumes:  Find references in inspirehep.net, click on bibtex to get the text of the citation. Add it to the file common/citedb.bib. Use the label as given in the inspirehep citation text in your latex file as \cite{label}

Common Errors 

  1. Use the term “comprise” to mean “include” not “compose.” The word comprise means “to be composed of.”
  2. Verbiage does not mean “text.” It means wasted or superfluous text.
  3. Enormity does not mean huge as in enormous. Enormity means evil.
  4. Do not interchange the words “affect” and “effect.” Affect is used as a verb and effect is almost always used as a noun to mean the result of a cause. Some exceptions apply.
  5. Use “impact” as a noun and not as a verb to mean affect.
  6. Use of “less” and “fewer.” Fewer is associated with quantity that can be counted. Less is associated with volume or mass.
  7. Use of the word “concur” You concur with someone and you concur in an idea or an opinion. The opposite holds good with the word “disappoint.” You are disappointed with something and disappointed in someone.


Issues to Fix

(there will surely be some!)