Wikipedia:Please clarify | how to improve articles that need clarification

How to improve articles that need clarification

  • Explain jargon: Define technical terms:
    • Add a brief definition when first using new terms, like: blog (a web log of journal entries)
    • Add a link to an unfamiliar topic
    • Define extra terms early (such as: Related terms include:)
    • Explain regional variations and the slang of certain professions (e.g. "Massachusetts rotary")
  • Could it be shorter?: Some guidelines which often help:
    • Delete extraneous rambling words (especially weasel words and/or peacock terms)
    • Replace clauses with adverbs (to limit prepositions to about four per sentence)
    • Replace longer words with shorter words
    • Split long sentences into shorter sentences (again, four prepositions per sentence)
    • Use idioms, or familiar phrases: rather than "electron flow field" use "electric current"; replace "computer program text" with "source code"; idioms seem simpler: as in "viewpoint" vs. "idiosyncratic approach to the perceived issue"
Compare two sentences: "Notwithstanding the controversy, she, with practiced skill, proceeded to navigate MegaX Corporation through difficult financial straits" versus "Despite the controversy, she navigated MegaX through difficult financial straits" (two prepositions, and note the removal of non-neutral assessment).
  • Add a diagram or photo: Complex text might be illustrated by a diagram. Wikimedia Commons also has over 12 million images, which can be searched (such as for "galaxy"). Even if the image or diagram is not exact, mention extra details in the caption-area, or use Template:Superimpose or Template:Location map to overlay a custom label/symbol onto an image.
  • Add a wikitable or list: Multi-column wikitables could clarify groups of data; however, simple lists (with colon-asterisk ":*" bullets) might be enough. See: spark plug, with a list of risks/benefits.
  • Make it clear what's happening and to what: A common example is a vague pronoun reference: "Emily was friends with Francine until she changed her job" (vague: Who changed jobs? Pronoun "she" equally applies to both). Also referring back to a list but not specifying the entry.
  • Use specific wording rather than vague whenever possible: For example, instead of saying, "in the old days", specify the time period you are referring to (say, the 19th century, or the 1960s).
    • Similarly, do not reference "now": the word "Recently" or "Soon" or their synonyms will become meaningless quickly. Use "As of" or a specific date.
  • Make sure you're using the right word(s): In one of the great critiques of a fellow author, Mark Twain listed eighteen rules of writing romantic fiction violated by James Fenimore Cooper.[1] Besides the criticism of Cooper's characterisation and plot, Twain also said that a writer should:
    • Avoid slovenliness of form
    • Employ a simple and straightforward style
    • Eschew surplusage (see KISS principle)
    • Not omit necessary details
    • Say what he is proposing to say, not merely come near it. (Avoid euphemisms; we don't have to bowdlerize)
    • Use good grammars
    • Use the right word, not its second cousin
  • Check your intent: Wikipedia is a place to inform and to educate. It is not a technical journal. Information from technical journals might need to be reduced to short sentences (four prepositions), because some journals encourage writing multi-level sentences spanning fifteen lines, with sub-sub-clauses.
  • Check your spelling: Usually misspelled words are obvious in their intent (e.g., "Qualty" is obviously "Quality"), however "Tedting" could be "Testing" or "Texting" (or "editing"). If it is not actually misspelled, or it is intended to be so, use the {{Sic}} template.
  • Make use of headings: A huge block of text can be daunting, but dividing it into sections, and subsections, can organize a logical structure onto the text, separating statements into each grouped section.