Saturday, April 14, 2012

Markup - What are the colors and symbols Vince uses when editing?

Q: What do these colors mean?
A: I often use the following highlight colors to indicate certain writing issues
  • ORANGE = wdy = wordy, verbose: Too many words express a desired thought or concept; try to shorten or condense the phrasing or simply omit unnecessary words; also repetitive and/or run-on sentences
  • YELLOW = grammar, misplaced modifiers, usage, spelling, articles, agreement, capitalization mistakes
  • GREEN = vague, illogical, imprecise or misleading; add prepositional phrases and details to fix the context and define the issues; show, don't tell
  • BLUE = not believable, not credible (esp. in recommendation letters) and trans = transition problem: A transition between paragraphs, arguments, or sections of the writing is nonexistent, abrupt, weak, lame or misleading.  Think about the logical relationship between the parts that need connecting and try to write a smooth and helpful transition.  Good transitions are based upon ideas and their logical relationship, not just clever or stock phrases. 
  • PINK = awk = awkward phrasing, although not grammatically incorrect. Most common: words with slightly inapposite meaning, too many words to express a particular concept, or awkward (but not technically incorrect) grammatical construction


    Q: What are some common symbols you insert when reviewing essays?
    A: I often use these:
    • agr = agreement, either subject/verb or pronoun/antecedent
    • awk = awkward phrasing, although not grammatically incorrect.  Most common: words with slightly inapposite meaning, too many words to express a particular concept, or awkward (but not technically incorrect) grammatical construction.
    • cs = comma splice
    • dm = dangling modifier
    • frag = [sentence] fragment, incomplete sentence: There is part of a sentence, but not enough to make a complete one.
    • cap = capitalize, use uppercase letters
    • lc = use lowercase letter
    • no = number: A number is used incorrectly in text. A common error is beginning a sentence with a number in numerical form. Although sentences may begin with numbers in spelled-out form, numbers in numerical form are not used to begin sentences. The second most common error is failing to spell out numbers less than ten.
    • pv = passive voice: Passive constructions ("the case was decided" or "it was determined that . . .") are grammatically correct but weak and often confusing. They are useful only when the subject of the verb is unknown or indefinite or the writer wishes to conceal the subject. Otherwise, passive voice—particularly if used repeatedly—is a sign of wooden and heavy writing, not a good style for advocacy! Better: "the court decided the case" or "the judge determined that . . ."
    • sp = spelling error or "spell out": This signal indicates a spelling mistake, a typographical error, the improper use of an abbreviation instead of the complete word or words, or the failure to spell out numbers less than ten.
    • spchk = use spellcheck
    • trans = transition problem: A transition between paragraphs, arguments, or sections of the writing is nonexistent, abrupt, weak, lame or misleading.  Think about the logical relationship between the parts that need connecting and try to write a smooth and helpful transition.  Good transitions are based upon ideas and their logical relationship, not just clever or stock phrases. 
    • v = verb form or forms are incorrect. The most common error of this type is disagreement between the number of the subject of the sentence and the number of the verb ("she see" or "they talks"). Another common problem occurs in series of nouns with "and" or "or;" in "or" series the number of the verb should agree with the noun that is closest to the verb in the sentence. Correct: "A lapse, an error, or omissions in text make it difficult to read." (In this sentence, the plural verb form "make" is correct because the plural noun "omissions" is closest to the verb.) 
    • va = vague: A paragraph, sentence, clause, phrase, or word is vague, nonspecific, imprecise, or misleading.  The most common error is failure to include short prepositional phrases that tie things down. Vague (depending on context): "The court refused to decide the issue." Precise: "The court refused to decide the issue of proximate cause."
    • wdy = wordy, verbose: Too many words express a desired thought or concept; try to shorten or condense the phrasing or simply omit unnecessary words.
    • ww = wrong word
    • tr = transpose letters or words
    • # = add space

    Other General Abbreviations



    (examples from legal writing, but can apply to other forms of technical writing)
    viewed by Vince Ricci 7/7/10 12:00 PM
    A/D Analogy or distinction.  A portion of the writing begs for analogizing or distinguishing other cases, whether precedents or hypotheticals.  Try to compare the facts at issue explicitly with the facts of other cases and show, step by step, why the rationales of those cases, as applied to the factual similarities or differences, would require the same or a different result.  
    AUD Audience.  The approach is inappropriate for your audience.  Who your audience is should affect a number of characteristics of your writing, including the level of detail (see DET), the level of abstraction, as distinguished from a practical approach (see PRAC), and the tone of your writing (see TONE).  
    CL"Clearly," "clear," or "obvious."  These words, as well as words to the same effect, are a dead giveaway for writer's insecurity.  If something is really clear, you can show it with specific reasoning or argument.  If it is not, no amount of bare insistence will make it so.  Good lawyers look for words like this in their opponents' papers because these words indicate where arguments are weak, incomplete, or undeveloped.
    COLLColloquialism.  Contractions (such as "they'll," "don't," "won't," "isn't") and colloquial expressions ("plaintiff was screwed", "the nitty gritty", etc.) are not used in formal writing and are usually not used in writing to clients.  More formal or conventional phrasing should be substituted.  Colloquialisms can be used in writing to a client whom you know personally and well. (See AUD)
    COMPComplex sentence structure.  A sentence or clause is too long, complicated in form, or convoluted in meaning.  You should break it up into shorter, clearer parts.  If necessary, the order and priority of thoughts should be reconsidered.
    COMPARComparative.  A comparative form of an adjective is grammatically incorrect (e.g., "more better," "lastest"), the comparative form used does not exist ("legitimatest"), or the sentence does not make clear what is being compared with what.
    CONC?Conclusion?  A conclusion to a paragraph, section, or line of reasoning is missing, unclear, or incomplete.  (See also MS)
    CONJConjunction.  A conjunction appears to be missing or inappropriate.  Common errors are substituting "but" for "and" or "since" for "although."  This is often a problem of logic and meaning, not just grammar.
    CONS?Consequences?  The consequences of an argument, holding, result, conclusion or action should be explored.  The consequences may be practical, social, business, or economic.  
    DETDetail is excessive.  This comment occurs most often when a description of the facts of a case is excessively detailed and lengthy, or when irrelevant details obscure legally relevant facts.  Summarize, condense, and select legally relevant facts for discussion.  Focus, focus, focus!
    DPDangling participle: a participial form of a verb has no matching subject, or what appears to be the subject does not match or make sense. Incorrect: "Turning to the second element of the tort, causation was inadequately proved."  It is not "causation" that turns, but "we" or the writer; therefore the participle "turning" has no real subject in the sentence and is dangling.  Dangling participles can be corrected by adding a subject or rewriting the sentence.  Correct: "Turning to the second element of the tort, we see [or "I note," or "the court ruled"] that causation was inadequately proved."  OR "With regard to the second element of the tort, causation was lacking."
    EEllipsis has (or appears to have) incorrect form.  An ellipsis should: (1) have spaces between the three or four periods; (2) use four periods (with intervening spaces) when the material omitted includes the end of a sentence; and (3) put the first of four periods immediately adjacent to the preceding text (without a space) when—and only when—a sentence in the quoted material ended there.
    ECONEconomics.  Does the statement noted make economic sense?  Does it cohere with currently accepted economic theory or not?  What economic consequences does it implicate (see also CONS, PRAC)?
    FACTSThe facts needed to understand or appreciate a case, judicial decision, argument or hypothetical are missing, incomplete, inaccurate, or misleadingly stated.  The most common errors are failing to state any facts at all, failing to select the most important and relevant facts, and failing to indicate, by context or verbal signals, how the key facts relate to a result, holding, or rationale.  (This problem occurs most often in argumentative writing.)
    GARBGarbled sentence, phrase, or clause.  Something is missing, misplaced, or distorted, but what and how is not clear.  Rethink and/or rewrite.
    GRAMGrammatical error (nonspecific).  Common errors include: (1) disagreement in number between noun and pronoun (using "they" for singular nouns), and (2) confusing "like" and "as" ("like" is a preposition, "as" is an adverb).
    ICInconsistent.  This signal may refer to ideas, words, or grammatical form.  A common error is inconsistency in style, for example, using singular and plural words indiscriminately for the same thing.  A more important error is using inconsistent words for the same thing, such as "employee" and "plaintiff" alternately for the same party.  Unlike creative writing (in which you may have been taught to use the Thesaurus and vary your use of words), legal writing requires consistency.  The goal is not variety and versatility, but straightforward and unmistakable communication.  This objective requires picking the best term for a single concept and sticking with it throughout a document.
    INNInnuendo.  Business writing should, insofar as possible, avoid innuendo or implication.  Instead, it should state all assumptions, facts, steps in reasoning, and conclusions explicitly.  It should leave little or nothing to chance or to the reader's intelligence or imagination.  Try to state directly and explicitly what you are implying.
    ISIncomplete sentence.  Sentence does not have both subject and verb or appears broken in the middle.
    LOLogical order.  The sentences, phrases, clauses or thoughts appear to be out of logical order.  Inserted numbers or letters (if present) designate parts or concepts that need re-ordering.
    LRLogical relationship.  The logical relationship between/among concepts, ideas, sentences, or clauses is unclear, because it is not stated, not stated explicitly enough, or not stated correctly.  This is a more general signal than LO (logical order) or NS (non-sequitur), and it may indicate more subtle problems.
    MANMore analysis needed.  The portion of text marked raises a question, begins an assessment or analysis, or suggests a line of reasoning or argument that begs for further development and analysis.  The same text also may invite or require further study and research. 
    MSMissing step or steps.  One or more steps in the logical reasoning or progression of the argument appear to have been omitted.
    MWMissing word or words.  A word or words appear to have been omitted, leaving the sentence, clause or phrase incomplete, ungrammatical, or nonsensical.  This signal is usually inserted at the place where words appear to be missing.
    NARROWA statement seems too narrow or timid.  Review the relevant facts or source of legal authority and consider broadening the statement by eliminating or changing conditions, qualifications, or limitations.  (Compare BROAD, QUAL)
    NEC?Necessary?  Asks whether particular words, phrases, clauses, or sentences are necessary to the writing or the argument, or are surplus or redundant.  Consider deleting or condensing the material marked.
    NSNon-sequitur (Latin: "it does not follow").  The marked sentence, clause or phrase does not logically follow from what comes before.  This may indicate a missing step in reasoning (see MS) or a more serious problem of substance.
    OOPOut of place—a general organizational error.  A paragraph, sentence, clause, or phrase appears out of place in terms of logic, chronology, or the flow of explanation or argument.  (See also LO, LR, POP, and TS)
    PLWPlacement of words.  The placement of words in a sentence is confusing or misleading.  The most common error is misplacing prepositional phrases, thereby creating ambiguities or unintended meanings.  This signal is similar to OOP (out of place) but refers to placement in a single sentence.
    POPThe point of a paragraph is unclear.  Generally speaking, every paragraph should have (and develop!) a single idea or theme, expressed in a short sentence or phrase.  Common problems are: unclear topic sentences or multiple themes (see TS), rambling, vagueness, and failure to come to a conclusion.  Unlike TS (topic sentence), this signal requires reassessing both the internal structure of the paragraph and its place in the larger organizational scheme of the document.
    POSPossessive.  A possessive form was omitted or incorrectly used.  The most common error is in ordering the apostrophe and the "s."  For example, "plaintiff's complaint" refers to a single plaintiff and "plaintiffs' complaint" to more than one.  The second most common error is forgetting that "it's" and "who's" are contractions (of "it is" and "who is," respectively).  They are not possessives and are not used in legal writing (see COLL).  The correct possessives are "its" and "whose," respectively, without apostrophes.
    QUOTQuotation error.  Most common errors: (1) omitting a quotation mark at the beginning or end of the quotation; (2) using duplicate double quotation marks ("), rather than single quotation marks (') for embedded quotations; and (3) failing to modify quoted language to fit into the grammatical structure of your writing and to indicate your modifications with square brackets ([]).
    QEQuoting excessively.  Too many quotes appear in succession, or quotations are too long.  Try to express all concepts and reasoning in your own words, keeping quotation to the minimum necessary to reflect absolutely essential nuances of what is quoted or words and phrases that may be or become terms of art.  (See also UOW).
    REDRedundant.  The same thing was already said somewhere else, or is said later in the writing.  This often indicates organizational error.
    TThe tense of a verb is incorrect, confusing, or not consistent with the tense of other verbs in the same paragraph or section of the document.  Normally, descriptions of the facts of cases and courts' reasoning should be in the past tense and statements of current law in the present.
    TONEThe tone of the writing is inappropriate for the audience (see AUD) or the situation.  Common problematic tones are: (1) condescension (e.g., in letter to client, "You may not know this, but . . ."), (2) insults, whether express or implied ("Only an idiot would conclude . . ."), (3) disrepect (to client: "You must do an IP audit." OR "You have made a bad mistake!"), and (4) insubordination (to client: "Make sure this brief is filed by next Wednesday."). Generally speaking, it is better to say the same thing more softly and diplomatically, in a way more likely to be received favorably, no matter who your audience may be.
    TSTopic sentence.  The topic sentence (of a paragraph) is missing or unclear or states more than one theme, or there is more than one candidate for the role of topic sentence.  The solution is: (1) to identify the main theme of the paragraph and any sentence or sentence fragment that states it; (2) to rewrite that sentence or fragment (or to write one if none exists) so as to state the theme clearly and concisely; (3) to rewrite the paragraph around that theme; and (4) to remove all extraneous material, including other candidates for topic sentences, to other paragraphs.  (See also POP)
    UCUnclear.  The meaning of a paragraph, sentence, clause, phrase or word (as marked) is unclear as stated.  Sometimes clarifying requires just rewriting; sometimes it requires rethinking what you are trying to say.
    UOWUse [your] own words.  Try to restate a quoted passage in your own words.  If you can point precisely and confidently to a term of art that must be used, or to a nuance that requires expression in the original words, use that term or the minimum number of original words needed, but try to rewrite everything else.  Using your own words makes the concepts your own, increases your understanding and appreciation, improves the flow of the paper, and avoids any tendency toward plagiarism.  (See also QE)
    VRVague reference, usually a pronoun.  Either the antecedent is indefinite because there is no specific noun within reasonable reach, or the antecedent is ambiguous because two or more specific nouns are near enough to serve grammatically, and the reader has to think to determine which is the right one.  The solution is simple: when in doubt, use a specific noun, not a pronoun or other general word.  

    This error also can occur with nouns.  The most common error is shifting from one noun to another in describing a particular person or thing, in such a way as to leave the reader in doubt regarding the antecedent.  Incorrect: "The plaintiff worked hard all year.  Then the defendant fired the employee without warning."  (Are the "plaintiff" and "employee" the same person?)  The solution is simply to use the same noun that was used in the antecedent or to add an explanatory or identifying phrase if that noun occurred too far back.
    W/CWord choice is incorrect.  Common errors of this type include confusing "effect" and "affect" and using "finds," "holds," "rules" and "opines" interchangeably.  A judge "finds" facts, "holds" as to law, "rules" on the result in a case or a principle of law, and "opines" if he/she is not in the majority.
    W/TWhich/that/who error.  Most common errors are: (1) failing to use a comma before a "which" or "who" clause that is explaining, rather than defining; (2) using a comma before such a clause that is defining; (3) using "who" (nominative case, used for subject of sentence) instead of "whom" (objective case, used for object of verb or preposition), or vice versa; (4) using "who" for an inanimate thing or "which" for an individual; or (5) using "that" when "which" would be better.

    "That" is permissible (and usually preferable) in defining clauses, that is, those clauses in which the pronoun should not be preceded by a comma.  Ordinarily "that" should not be used in explaining clauses, i.e., those that need a comma.  Correct: "Lawyers who are careless are unlikely to be successful."  [No comma is used because the "who" clause defines the type of lawyers meant by the speaker; without that clause the sentence does not make sense.  Here "that" could replace "who."] Also correct: "Distracted lawyers, who are often careless, may do their clients damage."  [Commas are required here because the "who" clause is explaining, not defining, and the sentence could stand without it.]
    WPWrong preposition.  For example, a person may have rights "in" or "to" property, so one may speak of copyright in a book, but not copyright "of" a book.   Most unabridged dictionaries point out the correct prepositions to use with particular words, either directly or by example.
    WS"Who is speaking?"  The writing fails to indicate the source of the thought or expression at issue, whether by context or explicit verbal signals (e.g., "the court said," "in the court's view," "in my view," "it seems").  You should rewrite to make clear whether the statement is yours, a court's, or another cited source's.
    1SPOne-sentence paragraph.  Although permissible in business letters and occasionally used for emphasis in briefs, one-sentence paragraphs are disfavored and rare in formal writing.  A one-sentence paragraph usually indicates one or more of the following organizational problems: (1) a missing or lame conclusion in the previous paragraph, (2) a missing or weak topic sentence in the following paragraph, (3) a poor, weak or nonexistent transition between paragraphs, or (4) failure to develop, expand, or support the idea underlying a topic sentence.
    //[Two parallel lines] Parallel structure is absent or incomplete.  This usually refers to a series that is not in grammatically parallel form.  Incorrect: "Suing requires filing a complaint, that the lawyer take lots of depositions, and zealous advocacy."  Correct: "Suing requires filing a complaint, taking lots of depositions, and advocating zealously."  OR "Suing requires commencement of the action, work on depositions, and zealous advocacy."
    // ORDParallel order of concepts is absent or incomplete.  Incorrect: "Judges and lawyers must be zealous and impartial."  Since judges are impartial and lawyers are zealous, correct writing requires reversing the order of one pair of words or the other.  This is true whether or not the word "respectively" is added to highlight the correspondence.









    -Updated by Vince on 20 April 2012


      Featured Post

      What are the five reasons to use passive voice?

      USE ACTIVE VOICE As listed below, there are only 5 reasons one should EVER use passive voice. If you don't need to use passive voi...