nanoHUB.org Style Guide 1.5

by Margaret Shepard Morris

Version 10
by (unknown)
Version 11
by (unknown)

Deletions or items before changed

Additions or items after changed

1 = '''nanoHUB.org Style Guide 1.0''' =
2
3 -
(need to split this file into Style Guide and Glossary, the program cannot handle so much text)
+
Style preferences are adapted from ''The Chicago Manual of Style'', 15th Ed. (CMS), and ''IEEE Standards Style Manual'' (IEEE). Please consult these references to resolve questions of style and usage on nanoHUB.org. For additional information on proper usage of field-specific terms, the NCN Editorial Team has compiled a nanoHUB Glossary.
4
5 -
In general, nanoHUB style adheres to ''The Chicago Manual of Style'', 15th Ed. (CMS), and ''IEEE Standards Style Manual'' (IEEE) to resolve questions of style and usage on nanoHUB.org
+
'''Audience consideration and informational density of a document'''
6 -
+
* In drafting and revising documents/texts for nanoHUB.org, keep the intended audience in mind. If a document is intended for multiple or mixed audiences, such as readers of different competencies and literacy levels, then authors must take care to tailor sections for those multiple or mixed audiences. The following table offers a guideline.
7 -
CMS and IEEE styles evolve with the advent of new technologies, genres, and conventions; for this reason, these guidelines are used by the nanoHUB editors to resolve questions of style throughout the website. Familiarity with CMS, then, is key also to maintaining consistency in nanoHUB materials, which are frequently written by multiple authors possessing different bases for style. In other words, when in doubt, see CMS or IEEE manuals.
+
8 -
+
9 -
Since the style manuals do not account for each particular of evolving terminology in the nano science and nanotechnology community, the NCN Editorial Team has compiled a nanoHUB Glossary for additional information on spelling, hyphenation, and capitalization of field-specific terms.
+
10 -
The Glossary represents the best editorial attempt to research how terms are used in the field and to represent them in such a way as to clarify language usage for nanoHUB users. Perhaps the glossary may also serve to help codify terms in the world of nano science communications.
+
11 -
The nanoHUB Style Guide and Glossary 1.0 is separated into the following sections: General Guidelines, Specific Guidelines, and the Glossary.
+
12 -
+
13 -
== General Guidelines ==
+
14 -
'''Audience consideration and informational density of a document''': In drafting and revising documents/texts for nanoHUB.org, authors must keep their intended audience in mind. The density of information in a document must be appropriate for the audience. If a document is intended for multiple or mixed audiences (readers of different competencies and literacies), then authors must take care to tailor sections for those multiple or mixed audiences. The following table offers general guidelines.
+
15
16 ||'''Feature of the document'''||'''Layperson/Undergraduate'''||''' Managerial/Graduate'''||'''Expert'''||
17 ||''Introduction''||Relevance||Problem/Solution||Technical||
18 ||''Mathematical models''||Avoid||Avoid||OK||
19 ||''Equations''||Avoid||Simple/Avoid||OK||
20 ||''Graphics''||Generally illustrative||Simple, presentational||Detailed, analytical||
21 ||''Detail level''||Simple, narrative||General, accurate||Accurate, numerical||
22 ||''Technical terms||General, illustratrive||Administrative||Expert, technical||
23 ||''Emphasis||Informational, interest||Operations, costs||Analysis||
24
25 -
In relation to the taxonomy of materials here at nanoHUB based on undergraduate and graduate education, authors can demonstrate consideration of the audience by using the appropriate level of detail. For example, the composition of a First-Time Users' Guide undergraduates will be most suited to the audience if the introduction of the document clearly states the relevance of the material to the readers' interests, mathematical models and equations are kept to a minimum, if not avoided entirely, any graphics are illustrative of points made clearly in the text, the detail level is kept simple and focused on providing a narrative, technical terms are carefully introduced by using the full English term at the first instance with a full description or definition, and only then using abbreviations.
+
* In relation to the taxonomy of materials here at nanoHUB based on undergraduate and graduate education, authors can demonstrate consideration of the audience by using the appropriate level of detail. For example, the composition of a "First-Time Users' Guide for Undergraduates" will be most suited to the audience if the introduction of the document clearly states the relevance of the material to the readers' interests. Mathematical models and equations are kept to a minimum, if not avoided entirely, any graphics are illustrative of points made clearly in the text, the detail level is kept simple and focused on providing a narrative, technical terms are carefully introduced by using the full English term at the first instance with a full description or definition, and only then using abbreviations.
26
27 ==Style Guide==
28 +
'''Forecasting'''
29 +
* Authors can use forecasting to inform readers where they need to turn for specific information. The introduction of a document might indicate which readers should begin with a specific section, and which readers can avoid certain sections. For example, "The VEDA manual is comprised of three sections: Part one, for first-time users, introduces readers to the software and guides them through simulations. The second part, for expert users, provides discussions of the theoretical models used to perform the simulations. . . ."
30
31 -
Authors can use forecasting to inform readers where they need to turn for specific information. For example, the introduction of a document can use the forecast of the structure of the document to indicate which readers should begin with a specific section, and which readers can avoid certain sections.
+
'''Font suggestions'''
32 -
+
* Titles, subtitles, and headings: Arial or Helvetica
33 -
The VEDA manual is comprised of three sections: Part one, for first-time users, introduces readers to the software and guides them through simulations. The second part, for expert users, provides discussions of the theoretical models used to perform the simulations. . . .
+
* Body paragraphs or table or figure descriptions: Times New Roman or Times
34 +
* Sections of code in papers or presentations: Courier or Courier New
35
36 -
General formatting
+
'''Figures and tables'''
37 +
* Both figure and table labels should be in bold font to set the descriptions apart from other body text. Figure labels appear below the figure, and table labels appear above the table.
38
39 -
Font suggestions:
+
'''Paper Title'''
40 -
Titles, subtitles, and headings: Arial or Helvetica
+
* In the paper title, capitalize the first letter of the first and last word and all the nouns, pronouns, adjectives, verbs, adverbs, and subordinating conjunctions (If, Because, That, Which). Capitalize abbreviations that are otherwise lowercase (e.g., use DC, not dc or Dc) except for unit abbreviations and acronyms. Articles (a, an, the), coordinating conjunctions (and, but, for, or, nor), and most short prepositions are lowercase unless they are the first or last word. Prepositions of more than three letters (Before, Through, With, Without, Versus, Among, Under, Between) should be capitalized.
41 -
Body paragraphs or table or figure descriptions: Times New Roman or Times
+
42 -
Sections of code in papers or presentations: Courier or Courier New
+
'''First Footnote'''
43 +
* The first footnote is made up of three paragraphs. This footnote is not numbered. All other footnotes in the paper are numbered consecutively.
44 +
* The first paragraph contains the received and (possibly) revised dates of the paper. When a paper has more than one revised date, list all the dates given.
45 +
* The second paragraph is made up of the authors’ affiliations. For two or more authors with different affiliations, use separate sentences and paragraphs for each, using all initials with a surname. Group the authors with the same affiliation together; list the affiliations according to the order of the authors in the byline.
46 +
* The third or final paragraph lists the Digital Object Identifier (DOI) number, assigned by the IEEE.
47 +
* All financial support for the work in the paper is listed next to the first paragraph and not in the Acknowledgment at the end of the paper.
48
49 -
Figures and tables:
+
'''Abstract'''
50 -
Both figure and table labels should be in bold font to set the descriptions apart from other body text. Figure labels appear below the figure, and table labels appear above the table.
+
* Every published paper must contain an abstract. Abstracts appear in text in boldface type. By nature, abstracts shall not contain numbered mathematical equations or numbered references.
51 -
+
52 -
+
53 -
Paper Guidelines
+
54 -
+
55 -
From IEEE Editorial Style Manual:
+
56 -
Parts of a Paper
+
57
58 -
Paper Title
+
'''Index Terms'''
59 -
In the paper title, capitalize the first letter of the first and last word and all the nouns, pronouns, adjectives,
+
* All papers must contain index terms as provided by the authors. A list of keywords is available by sending a blank email to keywords@ieee.org. Index Terms appear in boldface type as in the abstract, in alphabetical order, and as a final paragraph of the abstract. Acronyms are defined in index ierms if they are defined in the paper.
60 -
verbs, adverbs, and subordinating conjunctions (If, Because, That, Which). Capitalize abbreviations that are
+
61 -
otherwise lowercase (e.g., use DC, not dc or Dc) except for unit abbreviations and acronyms. Articles (a, an, the),
+
62 -
coordinating conjunctions (and, but, for, or, nor), and most short prepositions are lowercase unless they are the first
+
63 -
or last word. Prepositions of more than three letters (Before, Through, With, Without, Versus, Among, Under,
+
64 -
Between) should be capitalized.
+
65 -
+
66 -
First Footnote
+
67 -
The first footnote is made up of three paragraphs. This footnote is not numbered. All other footnotes in the
+
68 -
paper are numbered consecutively.
+
69 -
The first paragraph contains the received and (possibly) revised dates of the paper. When a paper has more
+
70 -
than one revised date, list all the dates given.
+
71 -
The second paragraph is made up of the authors’ affiliations. For two or more authors with different
+
72 -
affiliations, use separate sentences and paragraphs for each, using all initials with a surname. Group the authors with
+
73 -
the same affiliation together; list the affiliations according to the order of the authors in the byline.
+
74 -
The third or final paragraph lists the Digital Object Identifier (DOI) number, assigned by the IEEE.
+
75 -
+
76 -
All financial support for the work in the paper is listed next to the first paragraph and not in the
+
77 -
Acknowledgment at the end of the paper.
+
78
79 -
Body of a Paper
+
'''Nomenclature'''
80 +
* Nomenclature lists (lists of symbols and definitions) generally follow the abstract and index terms and precede the introduction.
81
82 -
Abstract
+
'''Text Section Headings'''
83 -
Every published paper must contain an Abstract. Abstracts appear in text in boldface type. By nature,
+
* Standard specifications have been established for Transactions text section headings. There are four levels of section headings with established specifications: primary; secondary; tertiary; and quaternary heads.
84 -
Abstracts shall not contain numbered mathematical equations or numbered references.
+
* Enumeration of section heads is desirable, but not required. The author’s preference may be followed. However, the choice must be consistent throughout the paper.
85 -
+
* Primary headings are enumerated by Roman numerals and centered above the text.
86 -
Index Terms
+
* Secondary headings are enumerated by capital letters followed by followed by periods, flush left, upper and lower case, and italic.
87 -
All papers must contain Index Terms as provided by the authors. A list of keywords is available by
+
* Tertiary headings are enumerated by Arabic numerals followed by parentheses. They are indented one em, and run into the text in their sections, italic, upper and lower case, and followed by a colon.
88 -
sending a blank email to keywords@ieee.org. Index Terms appear in boldface type as in the Abstract, in alphabetical
+
* Quaternary headings are identical to tertiary headings, except that they are indented two ems, lower case letters are used as labels, and only the first letter of the heading is capitalized.
89 -
order, and as a final paragraph of the Abstract. Acronyms are defined in Index Terms if they are defined in the
+
* Reference and Acknowledgment headings are unlike all other section headings in text. They are never enumerated. They are simply primary headings without labels, regardless of whether the other headings in the papers are enumerated.
90 -
paper.
+
* Appendix headings are a special case. The primary heading(s) in the appendix or appendixes (note spelling of plural) are set according to the usual style, except that there is flexibility in the enumeration of the heading. The author may use Roman numerals as heading numbers (Appendix I) or letters (Appendix A). The appendix heading is not preceded by a Roman numeral. If there is only one appendix in the paper, the appendix heading is unnumbered and unnamed.
91 -
+
92 -
Nomenclature
+
93 -
Nomenclature lists (lists of symbols and definitions) generally follow the Abstract and Index terms and
+
94 -
precede the Introduction.
+
95 -
+
96 -
Text Section Headings
+
97 -
Standard specifications have been established for Transactions text section headings. There are four levels
+
98 -
of section headings with established specifications: primary; secondary; tertiary; and quaternary heads.
+
99 -
Enumeration of section heads is desirable, but not required. The author’s preference may be followed.
+
100 -
However, the choice must be consistent throughout the paper.
+
101 -
Primary headings are enumerated by Roman numerals and centered above the text.
+
102 -
Secondary headings are enumerated by capital letters followed by followed by periods, flush left, upper and
+
103 -
lower case, and italic.
+
104 -
Tertiary headings are enumerated by Arabic numerals followed by parentheses. They are indented one em,
+
105 -
and run into the text in their sections, italic, upper and lower case, and followed by a colon.
+
106 -
Quaternary headings are identical to tertiary headings, except that they are indented two ems, lower case
+
107 -
letters are used as labels, and only the first letter of the heading is capitalized.
+
108 -
Reference and Acknowledgment headings are unlike all other section headings in text. They are never
+
109 -
enumerated. They are simply primary headings without labels, regardless of whether the other headings in the
+
110 -
papers are enumerated.
+
111 -
Appendix headings are a special case. The primary heading(s) in the Appendix or Appendixes (note
+
112 -
spelling of plural) are set according to the usual style, except that there is flexibility in the enumeration of the
+
113 -
heading. The author may use Roman numerals as heading numbers (Appendix I) or letters (Appendix A). The
+
114 -
Appendix heading is not preceded by a Roman numeral. If there is only one Appendix in the paper, the Appendix
+
115 -
heading is unnumbered and unnamed.
+
116 -
+
117 -
+
118 -
Specific Guidelines
+
119 -
+
120 -
Abbreviations, acronyms, initialisms, and portmanteaus: Abbreviation is an umbrella term that covers acronyms, initialisms, and portmanteaus. Acronyms and initialisms are close cousins, with an acronym referring to terms drawn from the first letters of their parts and read as a single word (AIDS, NATO), and initialisms referring to terms that you read as a series of letters (NPR, ATM, AT&T). Portmanteaus are blended terms, combining the forms and meanings of two words (spin and electronics=spintronics). On the nanoHUB, abbreviations typically appear capitalized and without periods. The exception to this non-use of the period in an abbreviation is any lowercased abbreviation, such as, et al., p.m., or e.g. The use of portmanteaus on nanoHUB.org often takes the form of a tool name (e.g., MATLAB).
+
121 -
+
122 -
Use of abbreviations:
+
123 -
nanoHUB users come from a variety of educational backgrounds and levels of expertise. To aid novice users, abbreviations should be defined with the initial use. Also, as nanoHUB serves many scholars and researchers whose primary language is not English, abbreviations for non-field-specific terms (e.g., misc., ASAP, and FYI) should be avoided whenever possible.
+
124 -
Acceptable: "Carbon nanotubes (CNT) have interesting, structure-dependent electronic properties. In particular, CNTs can be a metallic or semiconducting depending on the way in which the carbon atoms are arranged in the CNT walls."
+
125 -
Unacceptable: "The program CNDO/INDO is a general purpose combination of the CNDO/S, CNDO/2, INDO, and INDO/S programs. It does RHF (open and closed shell) calculations only, no geometry optimizations, and does Multi-Reference CI. Transition metals are included."
+
126 -
+
127 -
Formatting:
+
128 -
Abbreviations, acronyms, and initialisms typically appear capitalized and without punctuation. Abbreviations for non-English terms are not italicized. Portmanteaus typically appear either entirely lowercase or with the initial letter capitalized, as is the case with tool names.
+
129 -
+
130 -
Capitalization: A few general rules for capitalization throughout the site and in supporting documents appear below. Field-specific terms that appear on nanoHUB are sometimes derived from proper nouns and sometimes not, so correct capitalization requires an understanding of these terms' origins. For a list of terms that need to be capitalized, as well as the rationale for capitalization, see the Glossary below.
+
131 -
+
132 -
Proper names:
+
133 -
Words derived from proper names should be capitalized (e.g., Green's function). Common terms like capacitors and transistors should not be capitalized. See field-specific names and terms for further elaboration. Tool names are proper names and should thus be capitalized.
+
134 -
+
135 -
Tool names:
+
136 -
Band Structure / band structure
+
137 -
(always two words; capitalization depends upon context/usage as there is a proper noun and a common noun usage)
+
138
139 -
With a colon:
+
'''Abbreviations, acronyms, initialisms, and portmanteaus'''
140 -
The initial word after a colon should be uppercase if what follows the colon is a complete sentence; otherwise, the initial word after a colon will be lowercase
+
* ''Abbreviation'' is an umbrella term that covers acronyms, initialisms, and portmanteaus. Acronyms and initialisms are close cousins, with an ''acronym'' referring to terms drawn from the first letters of their parts and read as a single word (AIDS, NATO), and ''initialisms'' referring to terms that you read as a series of letters (NPR, ATM, AT&T). ''Portmanteaus'' are blended terms, combining the forms and meanings of two words (spin and electronics=spintronics). On the nanoHUB, abbreviations typically appear capitalized and without periods. The exception to this non-use of the period in an abbreviation is any lowercased abbreviation, such as, et al., p.m., or e.g. The use of portmanteaus on nanoHUB.org often takes the form of a tool name (e.g., MATLAB).
141
142 -
Citations: All citations should conform to IEEE guidelines. See <http://standards.ieee.org/guides/style/>
+
'''Use of abbreviations'''
143 +
* nanoHUB users come from a variety of educational backgrounds and levels of expertise. To aid novice users, abbreviations should be defined with the initial use. Also, as nanoHUB serves many scholars and researchers whose primary language is not English, abbreviations for non-field-specific terms (e.g., misc., ASAP, and FYI) should be avoided whenever possible.
144 +
* Acceptable: "Carbon nanotubes (CNT) have interesting, structure-dependent electronic properties. In particular, CNTs can be a metallic or semiconducting depending on the way in which the carbon atoms are arranged in the CNT walls."
145 +
* Unacceptable: "The program CNDO/INDO is a general purpose combination of the CNDO/S, CNDO/2, INDO, and INDO/S programs. It does RHF (open and closed shell) calculations only, no geometry optimizations, and does Multi-Reference CI. Transition metals are included."
146
147 -
Footnotes:
+
'''Formatting'''
148 -
Bracketed footnote indicators should follow a space: e.g. transport [7] rather than transport[7].
+
* Abbreviations, acronyms, and initialisms typically appear capitalized and without punctuation. Abbreviations for non-English terms are not italicized. Portmanteaus typically appear either entirely lowercase or with the initial letter capitalized, as is the case with tool names.
149
150 -
Commas: Commas should generally be used (1) at the end of a dependent clause (or introductory clause) preceding a main clause; (2) between items in a list of three or more items, including before the conjunction "and" or "or"; (3) surrounding interjections and descriptive phrases; (4) separating two or more adjectives modifying a noun.
+
'''Capitalization'''
151 +
* A few general rules for capitalization throughout the site and in supporting documents appear below. Field-specific terms that appear on nanoHUB are sometimes derived from proper nouns and sometimes not, so correct capitalization requires an understanding of these terms' origins. For a list of terms that need to be capitalized, as well as the rationale for capitalization, see the Glossary below.
152
153 -
Dates:
+
'''Proper names'''
154 -
Preferred style of dates (month day, year) requires a comma between the date and the year. SHOULD WE BEND HERE TO THE REST OF THE WORLD'S DATE PROTOCOL OF day month year? [YES!!!--MA]
+
* Words derived from proper names should be capitalized (e.g., Green's function). Common terms like capacitors and transistors should not be capitalized. See field-specific names and terms for further elaboration. Tool names are proper names and should thus be capitalized.
155 -
+
156 -
Clauses and use of commas:
+
157 -
Commas should not be inserted before a restrictive subordinating clause. If the subordinating clause is essential to the meaning of the main clause, commas preceding the subordinate clause are not needed. need example
+
158
159 -
Font choice:
+
'''Colons'''
160 -
Because sans serif fonts can lead to confusion of characters 1, l, and I, content of body paragraphs and text-heavy explanations should appear in a serif font, preferably a readily available on like Times New Roman or Times. Titles and headings can appear in sans serif font (Arial or Helvetica) so as to indicate a clear distinction between titles and headings and body content. Sections of code that appear in presentations and user guides should appear in a monospaced font (Courier) to distinguish examples of code from other sections of the document.
+
* The initial word after a colon should be uppercase if what follows the colon is a complete sentence; otherwise, the initial word after a colon will be lowercase
161
162 -
Commonly used fonts are discussed in a brief overview at:
+
'''Citations'''
163 -
http://web.mit.edu/jmorzins/www/fonts.html
+
* All citations should conform to IEEE guidelines. See <http://standards.ieee.org/guides/style/>
164
165 -
Names:
+
'''Footnotes'''
166 -
Author names:
+
* Bracketed footnote indicators should follow a space: e.g. "transport [7]" rather than "transport[7]."
167 -
Digital technologies allow for the inclusion of characters that could not be produced on a typewriters, so when possible, individual's names should appear as they have been entered. This means attention to spelling and the inclusion of non-English alphabet characters, such as umlauts, tildes, and accents. Authors are allowed to use initials instead of a full name, but initials should be capitalized and followed by a period and a space.
+
168
169 -
University names:
+
'''Commas'''
170 -
Spacing and punctuation conventions in university names are determined by state legislatures and universities, not popular convention. Be aware that faculty, students, and alum often incorrectly format university names, so err on the side of caution when relying on user-submitted content for examples. See university websites to determine proper formatting for university names.
+
* Commas should generally be used
171 +
# at the end of a dependent clause (or introductory clause) preceding a main clause
172 +
# between items in a list of three or more items, including before the conjunction "and" or "or"
173 +
# surrounding interjections and descriptive phrases
174 +
# separating two or more adjectives modifying a noun
175
176 -
Tool names:
+
'''Dates'''
177 +
* The style of dates "month day, year" requires a comma between the date and the year.
178
179 -
Supporting document titles:
+
'''Clauses and use of commas'''
180 +
* Commas should not be inserted before a restrictive subordinating clause. If the subordinating clause is essential to the meaning of the main clause, commas preceding the subordinate clause are not needed. need example
181
182 -
Site-specific/Preferred terms: (I'm guessing there should be something about branding here.)
+
'''Font choice'''
183 -
actively managed (replaces curate)
+
* Because sans serif fonts can lead to confusion of characters 1, l, and I, content of body paragraphs and text-heavy explanations should appear in a serif font, preferably a readily available on like Times New Roman or Times. Titles and headings can appear in sans serif font (Arial or Helvetica) so as to indicate a clear distinction between titles and headings and body content. Sections of code that appear in presentations and user guides should appear in a monospaced font (Courier) to distinguish examples of code from other sections of the document.
184 +
* Commonly used fonts are discussed in a brief overview at <http://web.mit.edu/jmorzins/www/fonts.html>
185
186 -
Available resource or Available resources (not Exercise/Exercises)
+
'''Author names'''
187 +
* Digital technologies allow for the inclusion of characters that could not be produced on a typewriters, so when possible, individual's names should appear as they have been entered. This means attention to spelling and the inclusion of non-English alphabet characters, such as umlauts, tildes, and accents. Authors are allowed to use initials instead of a full name, but initials should be capitalized and followed by a period and a space.
188
189 -
"Sponsored by" lines should omit "NSF" from before Network for Computational Nanotechnology.
+
'''University names'''
190 -
(NSF will remain if a specific grant number is listed.)
+
* Spacing and punctuation conventions in university names are determined by state legislatures and universities, not popular convention. Be aware that faculty, students, and alum often incorrectly format university names, so err on the side of caution when relying on user-submitted content for examples. See university websites to determine proper formatting for university names.
191
192 -
toward (not "towards")
+
'''Spacing guidelines'''
193 +
* Newer print and online publishing styles indicate a preference for single spacing where of double spacing used to be the standard. Chicago guidelines also stipulate that there should be one space between sentences instead of two. The same holds true of spacing following colons and semicolons.
194
195 -
Spacing guidelines:
+
'''Commonly Mistaken'''
196 -
Newer print and online publishing styles indicate a preference for single spacing where of double spacing used to be the standard. Chicago guidelines also stipulate that there should be one space between sentences instead of two. The same holds true of spacing following colons and semicolons.
+
* "Band Structure" / "band structure" are always two words. Capitalization depends upon context/usage as there is a proper noun and a common noun usage.
197 +
* "Towards" is not a word, but "toward" is.
198 +
* "Available resource" or "Available resources" should be used instead of "Exercise" or "Exercises"
199 +
* "Sponsored by" lines should omit "NSF" from before Network for Computational Nanotechnology. (NSF will remain if a specific grant number is listed.)