From edcb9c8fda28555551314e6fb797a6121b51efea Mon Sep 17 00:00:00 2001 From: Nathan Ryan Date: Mon, 11 Dec 2023 13:26:15 -0600 Subject: [PATCH 1/5] minor consistency updates --- manual/guides/writing/checklist.md | 85 +++++++++++++++--------------- 1 file changed, 42 insertions(+), 43 deletions(-) diff --git a/manual/guides/writing/checklist.md b/manual/guides/writing/checklist.md index 1c1281c0..6712f361 100644 --- a/manual/guides/writing/checklist.md +++ b/manual/guides/writing/checklist.md @@ -1,7 +1,7 @@ --- layout: manual title: Writing Checklist - subtitle: "Reduce clutter and increase clarity of any document with these rules" + subtitle: "Reduce clutter and increase clarity of any document with these rules." permalink: /manual/guides/writing/checklist/ --- @@ -12,16 +12,16 @@ This [writing checklist](/manual/guides/writing/checklist) is mostly from advice ## Reviewing Writing -Whether it's your own writing or someone else's, keep all of these sections in mind as you go through this list. +Use these lists to check off your progress in writing and reviewing. -```markdown +```markdown - [ ] Run a spell checker. -- [ ] Get rid of unnecessary prepositional phrases -- author clearing throat (It can be shown that) -- [ ] Get rid of extraneous adverbs (very, really, quite, basically, generally) -- [ ] Get rid of there are / there is -- [ ] Get rid of extraneous prepositions (the meeting happened on monday -> the meeting happened monday) (they agreed that it was true -> they agreed it was true) -- [ ] Get rid of passive voice (is/was/are/were/be/been/am + past tense verb), replace with active voice -- [ ] Make sure to cite all images, methods, software, and empirical data. Review [the principles](https://www.force11.org/software-citation-principles) and try [CiteAs](https://citeas.org/about) if necessary. +- [ ] Get rid of unnecessary prepositional phrases -- author clearing throat (e.g., It can be shown that...). +- [ ] Get rid of extraneous adverbs (very, really, quite, basically, generally). +- [ ] Get rid of there are / there is. +- [ ] Get rid of extraneous prepositions ("the meeting happened on Monday" -> "the meeting happened Monday") ("they agreed that it was true" -> "they agreed it was true"). +- [ ] Get rid of passive voice (is/was/are/were/be/been/am + past tense verb), replace with active voice. +- [ ] Cite all images, methods, software, and empirical data. Review [the principles](https://www.force11.org/software-citation-principles) and try [CiteAs](https://citeas.org/about) if necessary. ``` ## Enhancing Clarity @@ -30,51 +30,50 @@ As Shakespeare wrote in *Hamlet*, "Brevity is the soul of wit." ```markdown - [ ] Be concise and direct. -- [ ] The use of "very" suggests that a cooler word exists, replace where possible. -- [ ] Make sure that articles such as "a" "the" "some" "any" and "each" appear where necessary. -- [ ] Ensure all subjects must match the plurality of their verbs ( no: "Apples is tasty" yes: "Apples are tasty"). +- [ ] Using "very" suggests that a better word exists; replace it where possible. +- [ ] Make sure that articles such as "a," "the," "some," "any," and "each" appear where necessary. +- [ ] Ensure all subjects must match the plurality of their verbs (no: "Apples is tasty" yes: "Apples are tasty"). - [ ] Recover verbs that were turned into nouns ("obtain estimates of" -> "estimates"; "provides a description of" -> "describes"). -- [ ] Use the form ion of over ion. (For example, convert "calculation of velocity" to "velocity calculation".) -- [ ] Reduce vague words (important, methodologic). -- [ ] Reduce acronyms / jargon. +- [ ] Use the form ion of over ion (for example, convert "calculation of velocity" to "velocity calculation"). +- [ ] Reduce vague words like important or methodologic. +- [ ] Reduce acronyms/jargon. - [ ] Expand all acronyms on first use (rely on the acros.tex file and glossaries package to automate this). - [ ] Turn negatives to positives (she was not often right -> she was usually wrong). -- [ ] Don't bury the verb (keep the predicate close to the subject at the beginning of the sentence). +- [ ] Do not bury the verb (keep the predicate close to the subject at the beginning of the sentence). - [ ] Refer to software consistently by name. -- [ ] When you introduce words or phrases that are unusual or likely to be unfamiliar to the reader, italicize them. -- [ ] If you use an uncommon word, either consider changing it or define it in its first usage. +- [ ] Italicize unusual or likely unfamiliar words or phrases when you use them. +- [ ] If you use an uncommon word, consider changing it or defining it in its first usage. ``` ## Enhancing Style -You're a human writing for other humans: Make the wording exciting, and -remember some people reading it won't know as much jargon as you do. +You are a human writing for other humans: Make the wording exciting, and remember your audience includes readers who might not know as much jargon as you. ```markdown - [ ] Vary your sentence structure to keep readers engaged. - [ ] Do not use contractions in technical writing. - [ ] Use punctuation to help you to vary your sentence structure. -- [ ] Follow the convention that the power to separate in order of increasing power: comma, colon, dash, parentheses, semicolon, period -- [ ] In increasing order of formality: dash, parentheses, all of the others. Don't overdo the dash and parentheses +- [ ] Follow the convention that the power to separate is (in order of increasing power): comma, colon, em dash, parentheses, semicolon, and period. +- [ ] In increasing order of formality: dash, parentheses, all others. Don't overdo the em dash and parentheses. - [ ] Check that if there's a list in a sentence, it shouldn't come before the colon. - [ ] Always use isotopic notation like `$^{239}Pu$`. Never `$Pu-239$` or `$plutonium-239$`. -- [ ] Strengthen up your verbs (use sparingly: is, are, was, were, be, been, am). +- [ ] Strengthen your verbs (use sparingly: is, are, was, were, be, been, am). - [ ] Only use "large" when referring to size. - [ ] Do not use the word "when" unless referring to a time (try "if" instead). - [ ] Clarify or change misused/overused words where necessary (e.g., code, input, output, different, value, amount, model). - [ ] Each sentence/paragraph should logically follow the previous sentence/paragraph. -- [ ] Examples should use variables instead of numbers and use symbolic math instead of acronyms. +- [ ] Examples should use variables instead of numbers and symbolic math instead of acronyms. ``` ## Enhancing Grammar ```markdown -- [ ] "Data" is plural (the data are critical). -- [ ] Compare to (point out similarities between different things) vs. compared with (point out differences between similar things) +- [ ] "Data" is plural (e.g., "the data are critical"). +- [ ] Compare to (point out similarities between different things) vs. compared with (point out differences between similar things) - [ ] Elemental symbols (Ni, Li, Na, Pu) are capitalized, but their names are not (nickel, lithium, sodium, plutonium). -- [ ] Do not use the word "where" unless referring to a location (try "such that" or "in which"). +- [ ] Do not use the word "where" unless referring to a location (try "such that," or "in which"). - [ ] Avoid run-on sentences. - [ ] The preposition "of" shows belonging, relations, or references. The preposition "for" shows purpose, destination, amount, or recipients. They are not interchangeable. ``` @@ -82,51 +81,51 @@ remember some people reading it won't know as much jargon as you do. ## Enhancing Punctuation ```markdown -- [ ] Commas and periods go inside end quotes, except for when there's a parenthetical reference afterwards. +- [ ] Commas and periods go inside end quotes, except when there is a parenthetical reference afterward. - [ ] Colons and semicolons go outside closed quotations. -- [ ] Semicolon: connects two independent clauses. OR separates items when the list contain internal punctuation. +- [ ] A semicolon connects two independent clauses OR separates items when the list contains internal punctuation. - [ ] Use a colon to introduce a list, quote, explanation, conclusion, or amplification. -- [ ] The Oxford comma must appear in lists ("lions, tigers, and bears"). +- [ ] The Oxford comma must appear in lists (e.g., "lions, tigers, and bears"). - [ ] Use hyphens to join words acting as a single adjective before a noun (e.g., "well-known prankster"), not after a noun (e.g., "the prankster is well known"). -- [ ] Two words joined by a hyphen in title-case should both be capitalized. -- [ ] Hyphens join a prefix to a capitalized word, figure, or letter (e.g., pre-COVID, T-cell receptor, post-1800s); compound numbers (e.g., sixty-six); words to the prefixes ex, self, and all (e.g., "ex-sitter", "self-made", "all-knowing"); and words to the suffix elect (e.g., "president-elect"). +- [ ] Two words joined by a hyphen in title case should both be capitalized. +- [ ] Hyphens join a prefix to a capitalized word, figure, or letter (e.g., pre-COVID, T-cell receptor, post-1800s); compound numbers (e.g., sixty-six); words to the prefixes ex, self, and all (e.g., ex-sitter, self-made, all-knowing); and words to the suffix elect (e.g., president-elect). ``` ## Using Latin ```markdown -- [ ] The Latin abbreviations viz., i.e., and e.g. should all have commas before and after them (e.g., "We can classify a large star as a red giant, e.g., Stephenson 2-18."). -- [ ] The Latin abbreviations cf., et al., or q.v. should not have commas after them. +- [ ] The Latin abbreviations viz., i.e., and e.g. should all have commas before and after them (e.g., "We can classify a large star as a red giant, e.g., Stephenson 2-18"). +- [ ] The Latin abbreviations cf., et al., or q.v. should not automatically have commas after them. - [ ] The abbreviation of *versus* (vs.) should always have a period in American English and is used to contrast things. -- [ ] You should never say "and etc.," because "et" already means "and" in Latin. -- [ ] Abbreviations including et (e.g., "et al.") should not have a period after "et" because it is a whole word. -- [ ] Some abbreviations, but not the majority, need to be capitalized (e.g., "N.B." which means "note well"). -- [ ] Latin (or any Non-English) words, other than et, are usually italicized (e.g., *in situ, in vivo, in vitro,* and *ab initio*). +- [ ] You should never say "and etc.", because "et" means and in Latin. +- [ ] Abbreviations including "et" should not have a period after "et" because it is a whole word. +- [ ] Some abbreviations need capitalization (e.g., "N.B.," which means "note well"). +- [ ] Latin (or any non-English) words other than et are usually italicized (e.g., *in situ*, *in vivo*, *in vitro,* and *ab initio*). ``` ## Tables and Figures ```markdown - [ ] The text should refer to all tables and figures. -- [ ] When referring to figures by their number, use `Figure 1` and `Table 1.` They should be capitalized and not abbreviated (not `fig. 1` or `figure 1`.) +- [ ] When referring to figures by their number, use `Figure 1` and `Table 1.` They should be capitalized and not abbreviated (not `fig. 1` or `figure 1`). - [ ] Align all columns of numbers in tables such that the decimals line up. - [ ] All values should probably have the same number of significant digits in a single column. - [ ] Give units for each numerical column. -- [ ] A table should have only 3 horizontal lines (no vertical lines and no more than 3). +- [ ] A table should have only three horizontal lines (no vertical lines and no more than three). ``` ## Enhancing Math ```markdown -- [ ] Define all variables, with units. If unitless, indicate that this is the case `$[-]$`. +- [ ] Define all variables with units. If unitless, indicate this is the case `$[-]$`. - [ ] Subscripts should be brief and can be avoided with common notation. For example, `$\dot{m}$` is better than `$m_f$` which is superior to `$m_{flow}$`. - [ ] Variable names should be symbols rather than words `m` is better than `mass` and `\ksi` is better than `one_time_use_variable`. - [ ] The notation `$3.0\times10^{12}$` is preferred over `$3e12$`. - [ ] Equations should be part of a sentence. - [ ] Equations should be in the `align` environment. Align them at the `=` sign. -- [ ] Variables should be defined in the `align` environment as well, not buried in paragraphs. +- [ ] Variables should be defined in the `align` environment, not buried in paragraphs. ``` Here's an example of an equation: ```latex -The line is defined as +The definition of a line is \begin{align} y&=mx + b \intertext{where} From 5a0391e1b02c4c55aa61a839116715c1d56502b3 Mon Sep 17 00:00:00 2001 From: Nathan Ryan Date: Mon, 11 Dec 2023 13:39:08 -0600 Subject: [PATCH 2/5] spacing fix --- manual/guides/writing/checklist.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/manual/guides/writing/checklist.md b/manual/guides/writing/checklist.md index 6712f361..394bdee9 100644 --- a/manual/guides/writing/checklist.md +++ b/manual/guides/writing/checklist.md @@ -16,9 +16,9 @@ Use these lists to check off your progress in writing and reviewing. ```markdown - [ ] Run a spell checker. -- [ ] Get rid of unnecessary prepositional phrases -- author clearing throat (e.g., It can be shown that...). +- [ ] Get rid of unnecessary prepositional phrases -- author clearing throat (e.g., "It can be shown that..."). - [ ] Get rid of extraneous adverbs (very, really, quite, basically, generally). -- [ ] Get rid of there are / there is. +- [ ] Get rid of there are/there is. - [ ] Get rid of extraneous prepositions ("the meeting happened on Monday" -> "the meeting happened Monday") ("they agreed that it was true" -> "they agreed it was true"). - [ ] Get rid of passive voice (is/was/are/were/be/been/am + past tense verb), replace with active voice. - [ ] Cite all images, methods, software, and empirical data. Review [the principles](https://www.force11.org/software-citation-principles) and try [CiteAs](https://citeas.org/about) if necessary. From 53b9fdb1d104de4869611aea1d71f223168d081f Mon Sep 17 00:00:00 2001 From: Nathan Ryan Date: Tue, 23 Jan 2024 22:17:57 -0600 Subject: [PATCH 3/5] Remove contraction Co-authored-by: Sun Myung Park --- manual/guides/writing/checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manual/guides/writing/checklist.md b/manual/guides/writing/checklist.md index 394bdee9..15c9cea3 100644 --- a/manual/guides/writing/checklist.md +++ b/manual/guides/writing/checklist.md @@ -55,7 +55,7 @@ You are a human writing for other humans: Make the wording exciting, and remembe - [ ] Do not use contractions in technical writing. - [ ] Use punctuation to help you to vary your sentence structure. - [ ] Follow the convention that the power to separate is (in order of increasing power): comma, colon, em dash, parentheses, semicolon, and period. -- [ ] In increasing order of formality: dash, parentheses, all others. Don't overdo the em dash and parentheses. +- [ ] In increasing order of formality: dash, parentheses, all others. Do not overdo the em dash and parentheses. - [ ] Check that if there's a list in a sentence, it shouldn't come before the colon. - [ ] Always use isotopic notation like `$^{239}Pu$`. Never `$Pu-239$` or `$plutonium-239$`. - [ ] Strengthen your verbs (use sparingly: is, are, was, were, be, been, am). From 62db687b4e25c10484242e2976adcbf92488e6ea Mon Sep 17 00:00:00 2001 From: Nathan Ryan Date: Tue, 23 Jan 2024 22:33:38 -0600 Subject: [PATCH 4/5] address SM's comments --- manual/guides/writing/checklist.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/manual/guides/writing/checklist.md b/manual/guides/writing/checklist.md index 15c9cea3..f97bee06 100644 --- a/manual/guides/writing/checklist.md +++ b/manual/guides/writing/checklist.md @@ -32,16 +32,16 @@ As Shakespeare wrote in *Hamlet*, "Brevity is the soul of wit." - [ ] Be concise and direct. - [ ] Using "very" suggests that a better word exists; replace it where possible. - [ ] Make sure that articles such as "a," "the," "some," "any," and "each" appear where necessary. -- [ ] Ensure all subjects must match the plurality of their verbs (no: "Apples is tasty" yes: "Apples are tasty"). +- [ ] Ensure all subjects must match the plurality of their verbs (saying "Apples is tasty" is wrong, but "Apples are tasty" is correct). - [ ] Recover verbs that were turned into nouns ("obtain estimates of" -> "estimates"; "provides a description of" -> "describes"). -- [ ] Use the form ion of over ion (for example, convert "calculation of velocity" to "velocity calculation"). +- [ ] Use the form ion over ion of (for example, convert "calculation of velocity" to "velocity calculation"). - [ ] Reduce vague words like important or methodologic. - [ ] Reduce acronyms/jargon. - [ ] Expand all acronyms on first use (rely on the acros.tex file and glossaries package to automate this). - [ ] Turn negatives to positives (she was not often right -> she was usually wrong). - [ ] Do not bury the verb (keep the predicate close to the subject at the beginning of the sentence). - [ ] Refer to software consistently by name. -- [ ] Italicize unusual or likely unfamiliar words or phrases when you use them. +- [ ] Italicize unusual or unfamiliar words or phrases when you use them. - [ ] If you use an uncommon word, consider changing it or defining it in its first usage. ``` From 8cf901b51521996a6fb95ae7bd5538ca283b644c Mon Sep 17 00:00:00 2001 From: Nathan Ryan Date: Wed, 24 Jan 2024 11:09:50 -0600 Subject: [PATCH 5/5] address SM's example comments --- manual/guides/writing/checklist.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/manual/guides/writing/checklist.md b/manual/guides/writing/checklist.md index f97bee06..6a769e7b 100644 --- a/manual/guides/writing/checklist.md +++ b/manual/guides/writing/checklist.md @@ -35,7 +35,7 @@ As Shakespeare wrote in *Hamlet*, "Brevity is the soul of wit." - [ ] Ensure all subjects must match the plurality of their verbs (saying "Apples is tasty" is wrong, but "Apples are tasty" is correct). - [ ] Recover verbs that were turned into nouns ("obtain estimates of" -> "estimates"; "provides a description of" -> "describes"). - [ ] Use the form ion over ion of (for example, convert "calculation of velocity" to "velocity calculation"). -- [ ] Reduce vague words like important or methodologic. +- [ ] Reduce vague words like "important" or "methodologic." - [ ] Reduce acronyms/jargon. - [ ] Expand all acronyms on first use (rely on the acros.tex file and glossaries package to automate this). - [ ] Turn negatives to positives (she was not often right -> she was usually wrong). @@ -125,7 +125,7 @@ You are a human writing for other humans: Make the wording exciting, and remembe Here's an example of an equation: ```latex -The definition of a line is +A line has the form \begin{align} y&=mx + b \intertext{where}