Wikipedia:Please clarify

From Wikipedia, the free encyclopedia

[edit] Purpose

This is an essay; it contains the advice and/or opinions of one or more Wikipedia contributors. It is not a policy or guideline, and editors are not obliged to follow it. Please update the page as needed, or discuss it on the talk page.

Shortcut: WP:CLARIFY WP:CONFUSE

This Wikipedia page explains the three wiki tags {{huh}} and {{what}} and {{clarifyme}} which will appear within the text of an article as the superscript note ^[clarify].

This page also explains tags "{{clarify}}" or "{{confusing}}" which appear as

All or part of this article may be confusing or unclear. Please help clarify the article. Suggestions may be on the talk page.

Contents 1 Purpose 2 Ways to avoid confusion 3 How to add this tag 4 References

Clarification templates such as "{{clarifyme}}" or "{{confusing}}" can be used to flag wording that is likely to be confusing to the average reader, because the wording combines too many unusual technical terms, in long sentences (more than 4 phrases), or else omits key information.

[edit] Ways to avoid confusion

• Explain jargon: Define technical terms:
  • Define extra terms early (such as: Related terms include: <list>).
  • Add a brief definition when first using new terms, like: blog (a web log of journal entries).
  • Relatedly, beware of regional variations and the slang of certain professions.

• Could it be shorter?: Some guidelines which often help:
  • Replace clauses with adverbs (to limit prepositions to about four per sentence).
  • Delete extraneous rambling words (especially weasel words and/or peacock terms).
  • 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 "point of view" (the "of" here is not in the limit of four prepositions).

Compare 2 sentences: "Notwithstanding the controversy, she, with practiced skill, proceeded to navigate MegaX Corporation through difficult financial straits" versus "Despite the controversy, she deftly navigated MegaX Corp. through difficult financial straits" (two prepositions).

• Add a diagram or photo: Complex text might be illustrated by a diagram. Wikimedia Commons also has over 2 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 sure to 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).

• 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:
  • Say what he is proposing to say, not merely come near it. (Avoid euphemisms; we don't have to bowdlerize)
  • Use the right word, not its second cousin.
  • Eschew surplusage (see KISS principle).
  • Not omit necessary details.
  • Avoid slovenliness of form.
  • Use good grammar.
  • Employ a simple and straightforward style.

• 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.

• 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 (IE. "Qualty" is obviously "Quality"), however "Tedting" could be "Testing" or "Texting".

[edit] How to add this tag

To add a tag asking for clarification, simply type {{huh}}, {{what}} or {{clarifyme}} to insert a little tag like this:

^[clarify]

or put {{clarify}} to mark an entire article or section, displaying the tag-box (as shown at top).

[edit] References

1. ^ Fenimore Cooper's Literary Offences by Mark Twain