User:Jongarrettuk/Better writing guide (current draft)

This article is a better writing guide. It is not, and will not become, policy. But it does contain advice on how to make an article look good.

This article is not about markup: see Wikipedia:How to edit a page for that.
This article is not about formal policy on style: see Wikipedia:Manual of Style for that.
Nor does this article offer advice on lists and disambiguation pages or images. See Wikipedia:Lists, Wikipedia:Disambiguation and Wikipedia:Picture tutorial for that.
And you may also want to read Wikipedia:How to write a great article and Wikipedia:The perfect article
And if you want to see what Wikipedia's finest articles look like now, and learn from following the best, have a look at Wikipedia:Featured articles.

So relax, this article contains no rules. Remember: If rules and guidance make you nervous and depressed, and not desirous of participating in the Wiki, then ignore them and go about your business. If you stay with us, we'll look at layout, writing style, how to make an article relevant to a reader and making an article clear and precise. We also offer some general guidance on a few miscellaneous issues at the end.

Layout

The layout of an article is important. Good articles start with some introductory material and then present their information using a clear structure. They are then followed by standard appendices showing such things as references and related articles.

Structure of the article

Introductory material

Good articles start with a brief lead section introducing the topic. We discuss lead sections in greater detail below. As the lead section comes above the first header, it is very rarely useful to put ==Introduction== . A common title for the first section of a longer article under the introductory paragraph is "Overview", although more specific section titles are generally to be preferred.

Size

Articles themselves should be kept relatively short. Say what needs saying, but do not overdo it. Articles, other than lists, should anyway aim to be less than 32kb in size. When articles grow past this amount of readable text, they should be broken-up to improve readability and ease of editing. There are also technical issues with editing articles over 32kb. Few editors will read an entire 50 or 70kb often poorly-structured article just to make sure a piece of info they want to put in is not already there. The result is that the information is misplaced, duplicated, or not put in at all.

Paragraphs

Similarly, paragraphs should be relatively short, as the eye gets tired of following solid text for too many lines, but not too short. Group similar items and sentences together to improve readability. A long paragraph can normally be split up into two or more separate paragraphs with similar themes. Conversely, a one-sentence paragraph is like a cannon-shot during the performance: it attracts so much attention that it had better be good. An entire article that consists of one-sentence paragraphs can normally be consolidated by theme into a few paragraphs.

Headings

Headings help make an article clearer and determine the table of contents, see Wikipedia:Section. Since headers are hierarchical, and some people set their user preferences to number them, you should start with ==Header== and follow it with ===Subheader===, ====Subsubheader====, and so forth. Yes, the ==Header== is awfully big in some browsers, but that can be fixed in the future with a style sheet more easily than a nonhierarchical article structure can be fixed.

While it may be preferable to use bullet points within a section instead of using sub-headings, bold fonts should not be used. Good HTML practice dictates that headers are marked up as headers. The degree to which subtopics should be kept on a single page or given their own pages is a matter of judgment.

Images

If the article can be illustrated with pictures, find an appropriate place to position these images. For more information, see Wikipedia:Picture tutorial.

Standard appendices

Certain optional sections go at the bottom of the article.

Quotations

Under this header, list any memorable quotations that are appropriate to the subject.

Related topics or See also

Put here, in a bulleted list, other articles in the Wikipedia that are related to this one. Eg:

Or for a less formal feel you can simply use this:

Long article layout

The length of a given Wikipedia entry tends to grow as people add information to it. This cannot go on forever: infinitely long entries would cause problems. So we must remove information from entries periodically. This information should not be removed from Wikipedia: that would defeat the purpose of the contributions. So we must create new entries to hold the excised information.

Articles covering subtopics

Wikipedia entries tend to grow in a way which lends itself to the natural creation of new entries. The text of any entry consists of a sequence of related but distinct subtopics. When there is enough text in a given subtopic to merit its own entry, that text can be excised from the present entry and replaced by a link. Some characteristics:

Longer articles are split into sections (each about several good-sized paragraphs long. Subsectioning can increase this amount)
Ideally many of those sections will eventually provide summaries of separate articles on the sub-topic covered in that section (a Main article or similar link would be below the section title)
Each article on each subtopics has a lead section
As a rule, they do not trigger a page size warning (in rare cases this rule must be broken since the point is to limit readable text, not markup and sometimes markup may push a page above 32kb).

Examples of entries that do this are:

Cricket, where the page is divided into different subsections that give an overview of the sport, with each subsection leading off to one or more articles covering subtopics and with a large 'See also' section at the end
History of the English penny, which is part of the 'History of the English penny series', as illustrated by a table on the right hand side of the article.

A smaller number of articles are split into a series of pages. An example of this style is Isaac Newton (in depth). In this instance there is one contents page for the whole series of pages.

Balance parts of a page

Where an article is long, and has lots of subtopics with their own articles, try to balance parts of the main page. Do not put overdue weight into one part of an article at the cost of other parts. In shorter articles, if one subtopic has much more text than another subtopic, that may be an indication that that subtopic should have its own page, with only a summary presented on the main page.

Which style to use?

Two styles, closely related, tend to be used for Wikipedia articles.

News style

Some Wikipedians advocate using a news style. News style is the prose style of short, front-page newspaper stories and the news bulletins that air on radio and television. It encompasses not only vocabulary and sentence structure, but the order in which stories present information, their tone and the readers or interests to which they cater.

Encyclopedia articles do not have to follow news style, but a familiarity with news style conventions may be a great help in planning the style and layout of an article.

Summary style

'Summary style' is an organisational style that is similar to 'news style' that works in the basic spirit of news style except it applies to topics instead of articles and lead section instead of lead sentences.

The idea is to distribute information in such a way so that Wikipedia can serve readers who want varying amounts of detail. It is up to the reader to choose how much detail they are exposed to. This is done by not overwhelming the reader with too much text at once by using progressively longer and longer summaries. This is the style followed by Cricket and History of the English penny referred to above.

Rationale

Wikipedia is not divided into a macropaedia and a micropaedia like Encyclopaedia Britannica is. We must serve both user types in the same encyclopedia. Summary style is based on the premise that information about a topic should not all be contained in a single article since different readers have different needs:

some readers need just a quick summary (lead section),
more people need a moderate amount of info (a set of multi-paragraph sections)
and yet others need a lot of detail (links to full-sized separate articles).

We must serve all groups.

Think of the reader

Wikipedia is an international encyclopaedia. The people who read it have different backgrounds, education and worldview from you. Try to make your article accessible to as many of them as possible. The reader is probably reading the article to learn. It's quite possible the reader knows nothing at all about the subject: the article needs to explain it to them.

Where possible, avoid using jargon. But again, consider the reader. An article entitled "Use of chromatic scales in early Baroque music" is likely to be read by musicians, and so technical details and jargon, linked to articles explaining the jargon, are appropriate.

But an article entitled "Rap music" is likely to be read by laymen who want a brief and plainly written overview, with links to more detailed information if available. If any jargon that is used, a brief explanation should be given in the article itself.

State the obvious

State facts which may be obvious to you, but are not necessarily obvious to the reader. Usually, such a statement will be in the first sentence or two of the article. For example, consider this sentence:

The Ford Thunderbird was conceived as a response to the Chevrolet Corvette and entered production for the 1955 model year.

Here no mention is made of the Ford Thunderbird's fundamental nature: it is an automobile. It assumes that the reader already knows this—an assumption that may not be correct, especially if the reader is not familiar with Ford or Chevrolet. Perhaps instead:

The Ford Thunderbird is a car manufactured in the USA by the Ford Motor Company.

But there is no need to go overboard. There is no need to explain a common word like "car". Repetition is usually unnecessary, for example:

Yokoi Shoichi was drafted into the Imperial Japanese Army in 1941.

conveys enough information. Thus, the following is redundant.

Yokoi Shoichi was a Japanese soldier in Japan who was drafted into the Imperial Japanese Army in 1941. He speaks Japanese.

Lead section

The lead section is the section before the first headline. It is shown above the table of contents (for pages with more than three headlines). It should establish significances, large implications and why we should care.

The first sentence

If the subject is amenable to definition, the first sentence should give a concise, conceptually sound definition in its opening sentence that puts the article in context. The title should be highlighted in bold the first time it appears in an article, but not thereafter. Nor should the title be linked: a reader will only get back to the same article.

For example, an article on Charles Darwin, should not begin with:

Darwin created controversy with the publication of Origin of Species...

But instead should begin with something like:

Charles Darwin (1809–1882) was a naturalist and geologist who proposed the modern theory of evolution....

Wikipedia:Manual of Style (biographies) has more on the specific format for biography articles.

A common context problem is writers linking a work from an author's page, say, and then starting an article with "A is his third novel..." without stating whose novel it is.

If the article is about a fictional character or place, say so. Readers might not know, for instance, that Homer Simpson is not a real person. Start with, for example:

Homer Simpson is a fictional character in the television series...

The rest of the lead section

Then proceed with a description. The definition should be as clear to the nonspecialist as the subject matter allows. If the article is long (more than one page), the remainder of the opening paragraph should summarize it. Remember, the basic significance of a topic may not be obvious to nonspecialist readers, even if they understand the basic definition. Tell them! For instance:

Peer review (known as refereeing in some academic fields) is a scholarly process used in the publication of manuscripts and in the awarding of money for research. Publishers and agencies use peer review to select and to screen submissions. At the same time, the process assists authors in meeting the standards of their discipline. Publications and awards that have not undergone peer review are liable be regarded with suspicion by scholars and professionals in many fields.

If the article is long enough to contain several paragraphs, then the first paragraph should be short and to the point, with a clear explanation of what the subject of the page is.

To avoid the table of contents being positioned too low, say lower than this position in a page, put __TOC__ at the top of the desired position.

The appropriate length of the lead section depends on the total length of the article. As a general guideline, the lead should be no longer than two or three paragraphs. The following specific rules have been proposed:

< 15,000 characters	15,000 characters - 30,000 characters	> 30,000 characters
one or two paragraphs	two or three paragraphs	three paragraphs (consider splitting up the article)

How to test

Here are some thought experiments to help you test whether you are setting enough context:

Does the article make sense if the reader gets to it as a random page? (Special:Randompage)
Imagine yourself as a layman in another English speaking country. Can you figure out what the article is about?
Can people tell what the article is about if the first page is printed out and passed around?
Would a reader want to follow some of the links?

Use other languages sparingly

It is fine to include foreign terms as extra information, but avoid writing articles that can only be understood if the reader understands the foreign terms. In the English-language Wikipedia, the English form does not always have to come first, sometimes the non-English word is better as the main text with the English in parentheses or set off by commas after it, and sometimes not. For example, see perestroika

Non-English words in the English-language Wikipedia should be given emphasis, usually italic. Non-English words should be used as titles for entries only as a last resort. Again, see perestroika.

English title terms with foreign origin can encode the native spelling and put it in parentheses. See, for example, I Ching (易經 pinyin yì jīng) or Sophocles (Σοφοκλης). The native text is useful for researchers to precisely identify ambiguous spelling, especially for tonal languages that do not transliterate well into the Roman alphabet. Foreign terms within the article body do not need native text if they can be specified as title terms in separate articles.

Use colour sparingly

Use colour sparingly. Computers and browsers vary: you cannot know how much colour is presented on the recipient's machine if any. Wikipedia is international: colours have different meaning in different cultures. Too many colours on one page make them look cluttered and unencyclopedic. Use the colour red only for alerts and warnings.

Use clear, precise and accurate terms

Use short sentences and lists

Use short sentences does not mean use fewer words. It means don't use unnecessary words and sometimes using full stops/periods rather than commas. Consider the view of William Strunk, Jr. in his 1918 Elements of Style:

Vigorous writing is concise. A sentence should contain no unnecessary words [and] 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 [or her] sentences short, or that he [or she] avoid all detail and treat his [or her] subjects only in outline, but that every word tell.

Principle of least astonishment

This is the principle that you should plan your pages and links so that everything appears reasonable and makes sense. If a link takes a surfer to somewhere other than what they thought it would, it should at least take them someplace that makes sense.

Example

A user wants to know about the nuclear power plant that exploded in Chernobyl. The page on "Chernobyl" redirects to "Chornobyl", an alternative spelling for that town. However, the user sees that a link to the desired page, Chernobyl accident, is placed prominently near the top of the Chornobyl page, and happily clicks on that.

Use of 'refers to'

The phrase refers to is often found near the beginning of Wikipedia articles. For example, the article Computer architecture once began by saying "Computer architecture refers to the theory behind the design of a computer." But that is not literally true; it would be better to say, "Computer architecture is the theory behind the design of a computer", as the article now does. Note that it is the words computer architecture that refer to a certain theory; computer architecture itself does not refer to any theory, it is a theory.

Sometimes it may be appropriate to say, for example, "The term Great Schism refers to either one of two schisms in the history of Christianity", but most often the simpler locution is better. If you mention the phrase Great Schism, rather than using that phrase to refer to one of the Great Schisms, then write the word in italics to indicate that.

Check your facts

Write stuff that is true: check your facts. Do not write stuff that is false. This might require that you check your alleged facts.

This is a basic part of citing good sources...even if you think you know something, you have to cite references anyway to prove to the reader that the fact is true. In searching for good references to cite, you might even learn something new.

Be careful about deleting material that may be factual. Frequently editors incorporate substantive material without providing a reference. If you should be inclined to delete something from an entry, first consider checking whether it is true. If material is factual, i.e. 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. So consider each fact provided as potentially precious. Is the context or overall presentation the issue? If the fact does not being 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.

Avoid blanket terms

Avoid blanket terms unless you have verified them. For example, the Montgomery County 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 would have been a good idea to describe the research done and sign it on the article's talk page.

Check your fiction

The advice about factual articles also applies to articles on fiction subjects. Further considerations need to be made when writing about fictional topics: 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

"Trillian was taken away from Earth by Zaphod when he visited a party."

write

"Trillian is a fictional character from Douglas Adams's radio and book series The Hitchhiker's Guide to the Galaxy. She was taken away from Earth in a spaceship when Zaphod Beeblebrox visited a party. Together with Zaphod, she explores the universe in the starship. " And so on.

Articles about fictional topics should not be simple book-reports, rather the topic should be explained through its significance on the work. The reader should be able to feel like they understand why a character, place, or event was included in the fictional work after reading an article about one.

A reader should be able to understand why this person/place/thing/event is relevant to the story.

It is generally discouraged to add 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, a character in a TV show, say, 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 TV show or a fictional universe itself than to create all sorts of stubs about its characters that nobody can find. And if you find a lot of related fiction stubs? Merge them! Make yourself a characters of X page, and go cut-and-paste crazy, leaving a solid characters article, and a trail of redirects in your wake.

from Stay on topic

The most readable articles contain a minimum of irrelevant (or only loosely relevant!) information. While writing an article you might find yourself digressing into a side subject. If you find yourself wandering off topic, consider placing the additional information into a different article, where it will fit more closely with the 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 aren't interested won't be distracted by it.

Pay attention to spelling

Pay attention to spelling, particularly of new page names. Articles with good spelling and proper grammar will encourage further contributions of good content. Proper spelling of an article name will also make it easier for other authors to link their articles to your article. Sloppiness in one aspect of writing can lead to sloppiness in others. Always do your best. It's not that big a deal, but why not get it right?

Use free Internet dictionaries like Ask Oxford, Merriam-Webster, Dictionary.com and a spell checker such as SpellOnline.com. See Wikipedia:Typo 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 OpenOffice.org.
Users of Unix-like systems can also use Konqueror to edit Wikipedia — it highlights misspelt words in text boxes.

For more information, refer to the Manual of Style.

Avoid peacock and weasel terms

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

Examples of peacock terms
an important...	one of the most important...	one of the best...
the most influential...	a significant...	the greatest...
Examples of weasel terms
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, or species of beetle is worth the reader's time, it will come out in the facts.

Example 1

Sometimes the way round using these terms is to back the statement up with a fact.

"The Yankees are one of the greatest baseball teams in history."

"The New York Yankees have won 26 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 name any opinion at all.

Example 2

Consider the following two examples. Which do you think makes for more interesting reading?

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.

William Peckenridge, eighth Duke of Omnium (1642? - May 8, 1691) was personal counsellor to 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.

The first example simply tells the reader that William Peckenridge was important. The second example shows the reader that he was important.

Example 3

If you wish to refer to an opinion, first make sure it is given by someone who holds some standing in that subject. A view on President Ford from Henry Kissinger is more interesting for the reader than one from your teacher at 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 wrote an open letter to George Bush. In it, he asked "George, are you able to read and write on an adult level?".

Exceptions

What we have described is not a rule. When repeating established views, it may be easier to just state "Before Nicholas Copernicus', most people thought the Sun revolved round the Earth" rather than go into details and sources for it. Particularly if the statement forms only a small part of your article. But do not be surprised if people later question the source or reword your phrase.

Make omissions explicit

Make omissions explicit when creating or editing an article. When writing an article, always aim for completeness. If for some reason you can't cover a point that should be covered, make that omission explicit. You can do this either by leaving a note on the discussion page or by leaving 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're reading doesn't 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 is nevertheless important to the subject. Add {{todo}} to the top of the talk page of articles for which you can establish some goals, priorities or things to do.

Other issues

Inappropriate subjects: If you are trying to dress up something that doesn't belong in Wikipedia—your band, your Web site, your company's product—think twice about it. Wikipedia is not an advertising medium or home page service. Wikipedians are pretty clever, and if an article is really just personal gratification or blatant advertising, it's not going to last long—no matter how "important" you say the subject is.
Categorisation: Because Wikipedia is not a long, ordered sequence of carefully categorised articles like a paper encyclopedia, but a collection of randomly-accessible highly interlinked ones, each article should contain links to more general subjects that serve to categorise the article.
Avoid making your articles orphans: Avoid making your articles orphans. Link and link. When you write a new article page make sure at least one other page links to it (preferably more to increase your chances that your article does not become an orphan through someone else's refactoring). Otherwise, when it falls off the bottom of the Recent Changes page it disappears into the Mists of Avalon. There should always be an unbroken chain of links leading from the Main Page to every article in the Wikipedia; following the path you would expect to use to find your article may give you some hints as to which articles should link to your article.
Links: When you do create links, link only one or a few instances of the same term; don't link all instances of it. See also: Wikipedia:Links
Pronouns: See m:Quest for gender-neutral pronouns and the discussion on this for ideas relating to the use of pronouns, particularly gender-neutral ones, in Wikipedia.
Integrate changes: When you make a change to some text, rather than appending the new text you'd like to see included at the bottom of the page, if you feel so motivated, please place and edit your comments so that they flow seamlessly with the present text. Wikipedia articles should not end up being a series of disjointed comments about a subject, but unified, seamless, and ever-expanding expositions of the subject.
Unimportant things are important, too: Remember the pleasure of reading about relatively unimportant subjects: the vice presidents, the discredited scientists, the character actors, the backwater cities, the extinct species, the trivial detail. Not everything is the best, the most important, or the most influential. If you can add interesting links to fringe subjects, do.
Avoiding common mistakes: It is easy to commit a Wikipedia faux pas. That's OK — everybody does it! But, here are a few you might try to avoid.
Make a personal copy: Suppose you get into an edit war. Or worse, a revert war. So you try to stay cool. This is good. Congratulations! However, what would be great is if you could carry on working on the article, even though there is an edit war going on, and even though the version on the top is the evil one favoured by the other side in the dispute.

So make a personal copy as a subpage of your user page. Just Start a new page at user:MY NAME/ARTICLE NAME, and copy and paste the wiki-source in there. Then you can carry on improving the article at your own pace! If you like, drop a note on the appropriate talk page to let people know what you're doing.

Some time later, at your leisure, once the fuss has died down, merge your improvements back in to the article proper. Maybe the other person has left Wikipedia, finding it not to their taste. Maybe they have gone on to other projects. Maybe they have changed their mind. Maybe someone else has made similar edits anyway (but of course, not as good as yours, as you have had more time to consider the matter). Try it. You might like it.

External Links

the Elements of Style

Link with uninformative description	Link with informative description
Common knowledge	Common knowledge. Editorial by Ben Hammersley, The Guardian, January 30, 2003. Discusses the Wikipedia idea and provides a general summary of the wiki concept.
The Memory Hole	The Memory Hole by Russ Kick, a website which "exists to preserve and spread material that is in danger of being lost, is hard to find, or is not widely known" [1]. It is regularly updated with new documents, which are often obtained by the editor himself through Freedom of Information Act requests. The site also provides links to reports on external sites.