Writing better articles
From AgeofWiki
This article is not a policy; it is simply a collection of advice on how to make an article look good. This article is not about markup used in AgeofWiki articles. See Help:Contents for that.
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.
| Table of contents |
|
|
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 such 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==</nokwiki> . 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. 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 clarify articles and compose the table of contents. Since headers are hierarchical, and some people set their user preferences to number them, you should start with <nowiki>==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 one may prefer 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. Whether extensive subtopics should be kept on one page or moved to individual pages is a matter of personal judgment. Subheadings should generally be in alphabetical order, especially if they list countries.
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).
Standard appendices
Certain optional sections go at the bottom of the article.
Related topics or See also
Put here, in a bulleted list, other articles in AgeofWiki that are related to this one.
• (link1)
• (link2)
Or for a less formal feel you can simply use this:
See also: (links)
External links
Put here, in list form, any web sites that you have used or recommend for readers of the article. Describe it if possible.
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.
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 AgeofWiki links. Don't put in links to external URLs linking text that we will want articles on AgeofWiki about. Put external links in an "External links" section at the end of the article.
References
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. For example:
- Pooh, W. T. & Robin, C. (1926). "How to catch a heffalump" in A. A. Milne (Ed.), The Karma of Kanga, pp. 23–47. Hundred Acre Wood: Wol Press.
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.
Long article layout
The length of a given AgeofWiki 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 AgeofWiki: that would defeat the purpose of the contributions. So we must create new entries to hold the excised information.
Articles covering subtopics
AgeofWiki 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 - see Template:Main)
- 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).
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 AgeofWiki articles.
News style
Some users 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 AgeofWiki 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 Peerage.
Think of the reader
AgeofWiki is an international encyclopedia. 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. For example: An article entitled "Use of chromatic scales in early Baroque music" is likely to be read by musicians, and so technical details 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 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:
- Timer” can be used to specify the length of time before the cinematic begins.
At no point does the sentence mention that “Timer” is a condition, which can be found in the Triggers menu.
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 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, would not begin with:
Darwin created controversy with the publication of Origin of Species...
But instead would begin with something like:
Charles Darwin (1809–1882) was a naturalist and geologist who proposed the modern theory of evolution....
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 nondesigner 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 nondesigner 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.
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 colour sparingly
Use colour sparingly. Computers and browsers vary: you cannot know how much colour is presented on the recipient's machine if any. AgeofWiki 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 means use only necessary words, and sometimes using periods rather than commas. It does not mean use fewer words. Consider the view of William Strunk, Jr. in his 1918 Elements of Style:
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.
Reduce every sentence to its essentials. Wordiness has no place in AgeofWiki. Conciseness, however, does not justify removing information from an article.
Principle of least astonishment
Using the principle of least astonishment, you should plan your pages and links so that everything appears reasonable and makes sense. If a link takes readers to somewhere other than where 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.
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.
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 AgeofWiki: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 [www.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.
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 AgeofWiki 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 AgeofWiki - think twice about it. AgeofWiki is not an advertising medium or home page service. Users 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 AgeofWiki 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 AgeofWiki; 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.
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. AgeofWiki articles should not end up being a series of disjointed comments about a subject, but unified, seamless, and ever-expanding expositions of the subject.
