L5r:Guide to writing better articles

This article illustrates some rough guidelines on what pages should and should not look like. You may also want to read Wikipedia:Wikipedia:How to write a great article and Wikipedia: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:Wikipedia:Featured articles.

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.

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 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. The headed sub-section should be retained, with a concise version of what has been removed under an italicized header, such as Fuller treatment is at History of Ruritania. Otherwise context is lost and the general treatment suffers.

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, as long as the second paragraph gets an introductory sentence to keep the reader on-track, even one as brief as "Other examples abound."

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: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, where they relate closely to text they illustrate. If there might be doubt, draw attention to the image in the text (illustration right). For more information, see Wikipedia: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.

Put here, in a bulleted list, other articles in the Wikipedia that are related to this one. Eg:
 * Related topics or See also
 * Wikipedia:Wikipedia:Manual of Style
 * Wikipedia:Wikipedia:How to edit a page

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

See also: Main Page, Recent changes

Put under this header, again in a bulleted list, any books, articles, web pages, etcetera that you used in constructing the article and/or recommend as sources of further information to readers. The most important thing is to include the complete citation information, just as you would for any other bibliography. The precise formatting is still debatable and can be fixed later.
 * References

All of this, however, applies mainly to sources other than books published for Legend of the Five Rings. For books within the setting, simply the full (and accurate) title is appropriate, as readers of this wiki will generally know the rest of the information (author, publisher, release date, etc) automatically. See also: L5R:Cite your sources.

Put here, in list form, any web sites that you have used or recommend for readers of the article. Describe it if possible.
 * External links


 * Yale Web Style Guide for web pages

Its code is:

If you link to another website, you should give your reader a good summary of the site's contents, and the reasons why this specific website is relevant to the article in question. If you cite an online article, try to provide as much meaningful citation information as possible. Examples:

Websites can take a long time to load, and a long time to evaluate. Try making it easier for the reader to choose which sites to visit. If a particular website is known to take a long time to load, or requires special software to interpret (for example, a large PDF file) then add a note to the description indicating this fact.

Don't use external links where we'll want Wiki links. Don't put in links to external URLs that are about information which we will want articles on this Wiki. Put external links in an "External links" section at the end of the article. For example, if you're writing an article about iaijutsu and you know of a great article online, don't just link the word "iaijutsu" to that article. Simply wikify the word iaijutsu, and add an "External links" section with an external link to the source.

Long article layout
Related articles: Wikipedia:Wikipedia:Long article layout; Wikipedia:Wikipedia:Article size

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 the Wiki -- that would defeat the purpose of the contributions -- so instead, we must create new entries to hold the excised information.

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.

Think of the reader
The L5R Wiki is open to all of the world, a diverse and multi-ethnic blend, to say the least. Despite this, every visitor will almost certainly have at least some familiarity with Legend of the Five Rings. Because of this, it is not necessary to be as careful stating obvious points, avoiding jargon, or expressing the fictional nature of the article as it is in Wikipedia. Simply link any important words (shugenja, katana, Yasuki family, etc.) and let the reader learn about them in their own article.

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. All good articles should have an introduction in the lead section.

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

The rest of the lead section
Then proceed with a description. 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 some readers, even if they understand the basic definition. Tell them! 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.

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:

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 beginner that has just found L5R and knows only the basics of the setting. 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 color sparingly
Use color sparingly, if you feel you must use it at all. 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 short sentences and lists
Use short sentences does not mean use fewer words. It means don't use unnecessary words and use 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 sentences short, or that he avoid all detail and treat his subjects only in outline, but that every word tell.

When you have written your draft, read it over and boil it down to the essentials. Wordiness has no place in the L5R Wiki. Avoiding wordiness, however, is not a valid excuse for deleting information from an article.

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.

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, 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. So 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
The advice about factual articles also applies to articles on fiction subjects, which will be the majority of articles within this Wiki. Although articles on works of fiction would generally have differences from factual ones (such as the perpetual present tense in which works of fiction exist), for the purpose of this Wiki -- to create an in-character encyclopedia of Rokugani topics -- all articles should be treated as if they were discussing actual, non-fictional topics.

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 are not interested will not 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, Dictionary.com, Google Define and a spell checker such as SpellOnline.com or SpellCheck.net.  See 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.
 * Some browsers, such as Konqueror on Unix-like systems or Safari on Mac OS X, have the ability to highlight misspelt words in text boxes.

Avoid peacock and weasel terms (disputed)
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 are really used to express a non-neutral point of view.

Believe in your subject. Let the facts speak for themselves. If your subject is worth the reader's time, it will come out in the facts.

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.

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 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 this is a collaborative encyclopedia &mdash; 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 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 : All material within the L5R Wiki should either relate to the Legend of the Five Rings setting or to the Wiki itself. Be sure to see L5R Wiki for a more detailed list of what should and should not be included.
 * Categorization : Because the L5r Wiki is not a long, ordered sequence of carefully categorized 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 categorize 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 editing). Otherwise, when it falls off the bottom of the Recent Changes page, it disappears entirely. There should always be an unbroken chain of links leading from the Main Page to every article; 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:Wikipedia:Links
 * 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, please place and edit your comments so that they flow seamlessly with the present text. 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 family daimyo, the reclusive Kuni, the Shosuro Actors, the backwater cities, 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 &#8212; everybody does it! But, here are a few you might try to avoid.