Editing Incubator escapee wiki:Writing better articles (section)

== Use clear, precise and accurate terms ==
=== Be concise ===
{{see also|WP:DETAIL|WP:BECONCISE}}
{{shortcut|WP:TERSE}}
Articles should use only necessary words. This does not mean using fewer words is always better; rather, when considering equivalent expressions, choose the more concise.
{{quote|Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he avoid all detail and treat his subjects only in outline, but that every word tell.|[[William Strunk, Jr.]] from the 1918 work, ''[[The Elements of Style]]''}}

Reduce sentences to the essentials. Wordiness does not add credibility to Wikipedia articles. Avoid circumlocutions like "due to the fact that" in place of "because", or "at the present time" for "currently". Ongoing events should be qualified with "as of {{CURRENTYEAR}}". 

Conciseness alone does not justify removing information from an article.

=== Principle of least astonishment ===<!-- This section is linked from [[Wikipedia:Redirect]] -->
{{selfref|For the principle of least astonishment as applied to potentially offensive content, see [[WP:Offensive material#least astonishment]] and [[wmf:Resolution:Controversial content]].}}
{{seealso|WP:NOTWHATFIRSTCOMESTOMIND|MOS:BOLDREDIRECT|WP:R#ASTONISH|WP:Principle of Some Astonishment}}
{{shortcut|WP:PLA|WP:LEAST|WP:ASTONISH|WP:SURPRISE}}
When the [[principle of least astonishment]] is successfully employed, information is understood by the reader without struggle. The average reader should not be shocked, surprised, or confused by what they read. Do not use provocative language. Instead, offer information gently. Use consistent vocabulary in parts that are technical and difficult. To work out which parts of the sentence are going to be difficult for the reader, try to put yourself in the position of a reader hitherto uninformed on the subject.

You should plan your page structure and links so that everything appears reasonable and makes sense.  A link should not take readers to somewhere other than where they thought it would go.

Avoid [[WP:EASTEREGG|Easter-egg links]], which require the reader to open them before understanding what's going on. Instead, use a [[appositive|short phrase or a few words]] to describe what the link will refer to once it's opened.

Similarly, make sure that concepts being used as the basis for further discussion have already been defined or linked to a proper article. Explain causes before consequences and make sure your logical sequence is clear and sound, especially to the layperson.

Ensure that [[Wikipedia:Redirect|redirects]] and [[Wikipedia:Hatnote|hatnotes]] that are likely to be useful are in place. 

We cannot control all astonishment – the point of an encyclopedia is to learn things, after all. But limiting the surprises our readers find within our articles' text will encourage rather than frustrate our readers.

=== Use of "refers to" ===
{{see also|Wikipedia:Wikipedia is not a dictionary#Fixing the introductory sentence: removing "refers to"|Wikipedia:Manual of Style/Lead section#First sentence}}
{{shortcut|WP:REFERS|WP:UMD}}

Phrases such as '''''refers to''''', ''is the name of'', ''describes'', or ''is a term for'' are sometimes used inappropriately in the first sentence of Wikipedia articles. 
For the vast majority of articles, the introduction is ''using'' a term, rather than ''mentioning'' it. This is known as the ''[[use–mention distinction]]''.

For example, the article [[Computer architecture]] once began with the sentence, "{{!xt|'''Computer architecture''' refers to the theory behind the design of a computer.}}"
That is not true: Computer architecture {{em|is}} the theory. The {{em|words}} "computer architecture" refer to the theory, but the article is not about the words; it is about the theory.
Thus it is better to say, "{{xt|'''Computer architecture''' is the theory behind the design of a computer.}}"

To speak easily of the scope of a [[hyponymy and hypernymy|hyponym]] without confusing the term for the thing, one can simply say that "[hyponym] is any of various [hypernym]" or "any of a class of [hypernym] with trait X", such as "A pine is any conifer in the genus ''Pinus'' of the family Pinaceae" (not "Pine refers to any tree in the genus ''Pinus'' of the family Pinaceae").

[[WP:Disambiguation|Disambiguation pages]] ''mention'' the term, so in such cases it is correct to write "{{xt|'''Great Schism''' may refer to either of two schisms in the history of Christianity: ...}}". However, a [[WP:What is an article?|content article]] should read "{{xt|There have been two '''Great Schisms''' in the history of Christianity}}".

=== Check your facts === <!-- This section is linked from [[Wikipedia:Check your facts]] -->
{{seealso|Wikipedia:Verifiability}}
{{shortcut|WP:FACTCHECK}}
Write material that is true: check your facts. Do not write material that is false. This might require that you verify your alleged facts.

This is a crucial part of [[Wikipedia:Citing sources|citing good sources]]: even if you think you know something, you have to provide references anyway to prove to the reader that the fact is true. Material that seems to naturally stem from sourced claims might not have been actually claimed. In searching for good references to cite, you might even learn something new.

Be careful about deleting material that may be factual. If you are inclined to delete something from an entry, first consider checking whether it is true. If material ''is'' apparently factual, in other words substantiated and cited, be extra careful about deleting. An encyclopedia is a collection of facts. If another editor provided a fact, there was probably a reason for it that should not be overlooked. Therefore, consider each fact provided as potentially precious. Is the context or overall presentation the issue? If the fact does not belong in one particular article, maybe it belongs in another.

Examine entries you have worked on subsequent to revision by others. Have facts been omitted or deleted? It may be the case that you failed to provide sufficient substantiation for the facts, or that the facts you incorporated may need a clearer relationship to the entry. Protect your facts, but also be sure that they are presented meaningfully.

==== Check your fiction ====<!-- This section is linked from [[Wikipedia:Disambiguation]] -->
{{shortcut|WP:CYF}}
{{Main|Wikipedia:Manual of Style (writing about fiction)}}

The advice about factual articles also applies to articles on fiction subjects. Further considerations apply when writing about fictional topics because they are ''inherently not real''. It is important to keep these articles verifiable and encyclopedic.

If you add fictional information, clearly distinguish fact and fiction. As with normal articles, establish context so that a reader unfamiliar with the subject can get an idea about the article's meaning without having to check several links. Instead of writing:

: {{!xt|'''Trillian''' is [[Arthur Dent]]'s girlfriend. She was taken away from Earth by [[Zaphod]] when he met her at a party. She meets Dent while travelling with Zaphod.}}

write:

: {{xt|'''Trillian''' is a [[fictional character]] from [[Douglas Adams]]'s radio, book and film series ''[[The Hitchhiker's Guide to the Galaxy]]''. In the first book, Trillian is introduced to the main character [[Arthur Dent]] on a spaceship. In her backstory, she was taken away from Earth when the space alien [[Zaphod Beeblebrox]] met her at a party.}}

==== Use of fictional tenses ====
{{shortcut|WP:FICTENSE}}{{anchor|Tense}}{{anchor|Tense in fiction}}
Works of fiction are generally considered to "come alive" for their audience. They therefore exist in a kind of perpetual present, regardless of when the fictional action is supposed to take place relative to the reader's "now". Thus, generally you should write about fiction using the ''[[Historical present#In describing fiction|historical present tense]]'', not the past tense. (See {{section link|WP:Manual of Style|Verb tense}} and {{section link|WP:Manual of Style/Writing about fiction|Contextual presentation}}.)
Examples:

: Homer ''{{xt|presents}}'', Achilles ''{{xt|rages}}'', Andromache ''{{xt|laments}}'', Priam ''{{xt|pleads}}''.
: {{xt|Holden Caulfield ''has'' a certain disdain for what he ''sees'' as 'phony'.}}
: {{xt|''Friends'' ''is'' an American sitcom that ''was'' aired on NBC.}}

Conversely, discussion of history is usually written in the past tense and thus "fictional history" may be presented in that way as well.

: {{xt|Chroniclers ''claimed'' that Thalestris, queen of the Amazons, ''seduced'' Alexander the Great.}}

Articles about fictional topics should not read like [[book report]]s; instead, they should explain the topic's significance to the work. After reading the article, the reader should be able to understand why a character, place, or event was included in the fictional work.

Editors are generally discouraged from adding fictional information from sources that cannot be verified or are limited to a very small number of readers, such as [[fan fiction]] and online role-playing games. In the latter case, if you absolutely have to write about the subject, please be especially careful to cite your sources.

If the subject, say a character in a television show, is too limited to be given a full article, then integrate information about that character into a larger article. It is better to write a larger article about the television show or a fictional universe itself than to create all sorts of stubs about its characters that nobody can find.

==== Stay on topic ====
{{Redirect|WP:TOPIC|information about the Topic namespace|Wikipedia:Flow}}
{{Redirect|WP:OFFTOPIC|the guideline on collapsing off-topic talk page discussions|Wikipedia:TALKOFFTOPIC}}
{{shortcut|WP:TOPIC|WP:OFFTOPIC}}
The most readable articles contain no irrelevant (nor only loosely relevant) information. While writing an article, you might find yourself digressing into a side subject. If you are wandering off-topic, consider placing the additional information into a different article, where it will fit more closely with that topic. If you provide a link to the other article, readers who are interested in the side topic have the option of digging into it, but readers who are not interested will not be distracted by it.

=== Pay attention to spelling ===
{{Main|Wikipedia:Spellchecking}}
'''Pay attention to spelling''', particularly of new page names. Articles with good spelling and proper grammar can help encourage further contributions of well-formed content. Proper spelling of an article name will also make it easier for other authors to link their articles to your article. Sloppiness begets sloppiness, so always do your best.
* Browsers have the native ability to highlight misspelled words in text boxes.
* Use free online dictionaries like [http://www.askoxford.com/ Ask Oxford], [http://www.dictionary.com/ Dictionary.com], [http://www.onelook.com/ Onelook.com], [//www.google.com/help/features.html#definitions Google Define] and a spell checker such as [http://www.spellcheck.net/ SpellCheck.net], [http://www.gingersoftware.com/spellcheck GingerSoftware], or your browser's built-in spell checker. See [[Wikipedia:Typo Team]] for tips on how to use these resources.
* Articles may also be spell-checked in a word processor before being saved. A free word processor may be obtained from [http://www.openoffice.org/ OpenOffice.org] or [https://www.libreoffice.org/ LibreOffice.org].
* A "draft" message on certain free email websites, such as [https://www.gmail.com/ Gmail], can also provide spell-check. This might be convenient, especially regarding email websites with which you are already familiar and use often.

=== Avoid peacock and weasel terms ===
[[Wikipedia:PEACOCK|Avoid peacock terms]] that show off the subject of the article without containing any real information. Similarly, [[Wikipedia:WEASEL|avoid weasel words]] that offer an opinion without really backing it up, and which are really used to express a non-neutral point of view.

{| border="0" cellpadding="2" cellspacing="0"
|- bgcolor="#efefef"
! colspan=3 style="border-right:0px;"; | Examples of '''peacock terms'''
|- bgcolor="#efefef"
|-
|an important...||one of the most prestigious...||one of the best...
|-
||the most influential...||a significant...||the great...
|-
|- bgcolor="#efefef"
! colspan=3 style="border-right:0px;"; | Examples of '''weasel words'''
|- bgcolor="#efefef"
|-
||Some people say...||...is widely regarded as...||..is widely considered...
|-
||...has been called...||It is believed that...||It has been suggested/noticed/decided...
|-
||Some people believe...||It has been said that...||Some would say...
|-
||Legend has it that...||Critics say that...||Many/some have claimed...
|}

Believe in your subject. Let the facts speak for themselves. If your [[ice hockey]] player, [[canton (administrative division)|canton]], or species of [[beetle]] is worth the reader's time, it will come out through the facts. However, in some cases (for example, history of graphic design) using superlative adjectives (in the "... ''one of the'' most important figures in the history of ..." format) in the description may help readers with no previous knowledge about the subject to learn about the importance or generally perceived status of the subject discussed. Note that to use this type of superlative adjective format, the most reputable experts in the relevant field must support the claim.

Avoid blanket terms unless you have verified them. For example, [[List of the most common U.S. county name etymologies#Montgomery County (18 counties)|this article]] states that of the 18 Montgomery Counties in the United States, '''most''' are named after Richard Montgomery. This is a blanket statement. It may very well be true, but is it reliable? In this instance, the editor had done the research to verify this. Without the research, the statement should not be made. It is always a good idea to describe the research done and sign it on the article's talk page.

If you wish to, or must refer to an opinion, first make sure someone who holds some standing in that subject gives it. A view on former American President [[Gerald Ford]] from [[Henry Kissinger]] is more interesting for the reader than one from your teacher from school. Then say who holds the opinion being given, preferably with a source or a quote for it. Compare the following:

:Some critics of [[George W. Bush]] have said he has low intelligence.

:Author [[Michael Moore]] in his book ''[[Stupid White Men ...and Other Sorry Excuses for the State of the Nation!]]'' wrote an open letter to George Bush. In it, he asked, "George, are you able to read and write on an adult level?"

==== Examples ====
Sometimes the way around using these terms is to replace the statements with the facts that back them up. Instead of:

:{{!xt|The Yankees are one of the greatest baseball teams in history.}}

Write:

:{{xt|The New York Yankees have won 27 World Series championships—almost three times as many as any other team.}}

By sticking to concrete and factual information, we can avoid the need to give any opinion at all. Doing so also makes for writing that is much more interesting, for example:

:{{!xt|'''William Peckenridge,''' eighth '''Duke of Omnium''' (1642? – May 8, 1691) is widely considered to be one of the most important men to carry that title.}}
:{{xt|'''William Peckenridge,''' eighth '''Duke of Omnium''' (1642? – May 8, 1691) was a personal counselor to [[James I|King James I]], general in the [[Wars of the Roses]], a chemist, bandleader, and the director of the secret society known as The League of Extraordinary Gentlemen. He expanded the title of Omnium to include protectorship of Guiana and right of revocation for civil-service appointments in India.}}

[[Show, don't tell]]. The first example simply ''tells'' the reader that William Peckenridge was important. The second example ''shows'' the reader why he was important.

==== Exceptions ====
When repeating established views, it may be easier to simply state: "Before [[Nicolaus Copernicus]], most people thought the sun revolved round the earth", rather than sacrifice clarity with details and sources, particularly if the statement forms only a small part of your article. However, in general, everything should be [[Wikipedia:Citing sources|sourced]], whether within the text, with a footnote, or with a general reference.
<!-- Actually knowledge of the earth's spherical shape was well-disseminated in ancient Greece, and for the past 50 years historians have known survived into the Middle Ages among the educated classes more widely than was previously believed, so actually this IS a good area for checking your sources. See Jeffrey Russell's book on the myth of the flat earth. -->

=== Make omissions explicit for other editors ===
'''Make omissions explicit''' when creating or editing an article. When writing an article, always aim for completeness. If for some reason you cannot cover a point that should be explained, ''make that omission explicit''. You can do this either by leaving a note on the discussion page or by leaving [[WP:COMMENT|HTML comments]] within the text and adding a notice to the bottom about the omissions. This has two purposes: it entices others to contribute, and it alerts non-experts that the article they are reading does not yet give the full story.

That's why Wikipedia is a collaborative encyclopedia—we work together to achieve what we could not achieve individually. Every aspect that you cover means less work for someone else, plus you may cover something that someone else may not think of but which is nevertheless important to the subject. Add <nowiki>{{</nowiki>[[Template:todo|To do]]<nowiki>}}</nowiki> to the top of the talk page of articles for which you can establish some goals, priorities or things to do.