CZ:Article Mechanics Complete

There is a briefer version of this document available.

While the Citizendium may not (yet) call itself an encyclopedia, its aim is to build up a body of articles that serve as encyclopedia articles. These articles cover, at a very general level, every aspect of their topics. Their broad scope is perhaps what most clearly distinguishes encyclopedia articles from ordinary expository essays. Therefore, the purpose of every article (as distinguished from lists and other supplementary material) in the Citizendium is to introduce every aspect (or many aspects) of the topic named in its title, but at a very general level.

Introductions differ from mere summaries or lists of information. An introduction is an extended, connected piece of prose, meant to be read all the way through. It is not merely a list of facts. It places what facts it presents into a context that makes them meaningful to someone who presumably needs an introduction. Indeed, the very notion of an introduction carries in it the idea that the topic introduced is new to its ideal reader.

Introductory articles, to be read and used by their intended audience, must be somewhat selective and simplified in the information they present. If an article contains information presented too densely, or in too abstract a way, it becomes merely a catalog or record of what experts know--of some interest to experts, perhaps, but not to people who actually need an introduction. This does not mean that an introduction must be brief, but that it spend the space needed to make whatever it does say clear to a university-level audience that is prepared to receive an entree to the topic. In other words, a Citizendium article is an opportunity to show off not your erudition but your ability to make the difficult seem easy.

Introductory material

Matter placed between the title and the first sentence

Do not place a heading, such as "Introduction" or "Preface" or "Definition," between the article title and the first sentence. The first heading belongs after the first section, which should always be introductory.

There must be an excellent reason to place anything between the title and first sentence of an article. Exceptions are few and enumerable.

Approval notices are always appropriate, as are links back to the article page from a draft page. (See Approval Process.)

Links to disambiguation pages (pages that point to several different articles that have the same title; think "Paris" or "Mars") should be placed only when there really is a need for such a link. Thus, for example, if we decide to use the page titled Paris for the French city, then considering that some people will go to that page looking for an article about the Greek hero under that title, we should probably have a disambiguation notice atop that page. On the page titled Paris (Greek hero), however, there is no need for such a disambiguation notice at the top of the page, because it is highly unlikely that anyone will arrive at Paris (Greek hero) looking for an article about any other sort of Paris.

Links to confusable pages (other pages with topics, but not necessarily names, that are easily confusable with the present page's topic; think ethics vs. morality, or fiddle vs. violin) are acceptable only if there really is a need for them. The rule we may use to make the decision whether to have a notice about a confusable page is: two pages, A and B, should interlink with "confusable page" notices only if the topics are commonly confused and readers can be expected to read A believing that they have found all the information the Citizendium has about B. For example, we might well have separate articles about ethics and morality. But these concepts are often not distinguished, and few people can say with any clarity what the difference is between them; moreover, it's entirely possible that someone might read our ethics article expecting to find all the information we have about morality, as well. In such a case, we should place a notice atop ethics saying, for example, "For the history of differences between actual moral practices, see morality. This article concerns the philosophical discipline." We would then place a similar notice atop morality.

Bold titles

In most articles, we should bold the title of the article. For example:

Philosophy, both the field and the concept, is notoriously hard to define. The question "What is philosophy?" is itself, famously, a vexing philosophical question. It is often observed that philosophers are unique in the extent to which they disagree about what their field even is.

But on some pages this is unnecessary, particularly where it would produce strange or nonsensical results. Such pages include lists, as in list of snake scales, or where the title of the article is an idiosyncratic phrase that does not name a single, particular item to be defined or briefly described, such as potassium in nutrition and human health.

The first sentence

What the first sentence of the article should look like depends on whether the article concerns a concept or, instead, a particular thing.

Generally, in articles about concepts, or where the word in the title has a definition, the first sentence in the article is a definition. For example:

Dermatology is the specialty of medicine concerned with the skin and with the skin appendages (hair, nails, sweat glands, etc.).

If, however, there is no agreed-upon definition, and particularly where the disagreement about the definition is an important aspect of the topic--one thinks of freedom or racism--it is preferable not to begin with a single (and controversial) definition. In such cases, it is actually preferable to begin in some other way, even by describing the difficulty of or the controversy over the concept. (See the "Philosophy" example above.)

In articles about particular things, such as persons, historical events, or publications, it is usually preferable to begin the article with a description of what the item in question is most notable for:

Princeton, New Jersey is located in Mercer County, New Jersey, United States, and is best known as the home, since 1756, of Princeton University.

William Shakespeare (baptised April 26, 1564 – died April 23, 1616) was an English poet and playwright widely regarded as the greatest writer of the English language, as well as one of the greatest in Western literature, and the world's preeminent dramatist.

Etymologies

Most etymologies of terms are not so interesting or important that they deserve more than cursory treatment. So, usually they should be placed in parenthetical clarifications

Physics (from the Greek physikos, nature) is the science of nature at its most fundamental form...

or even in footnotes, where the etymology is of interest, but ought not to interrupt the flow of the article.

But occasionally the etymology of a term is itself of such interest that it can be made a subject of its own sentence, paragraph, or even section:

The word morphology came into English in the mid 19th century from Greek words μορφή (morphi) meaning "shape or form" and λόγος (logos) meaning "speak". In English the suffix "-(o)logy" means "the study of". For ancient Greeks, study often involved a great deal of debate; and this is still true for scientists today.

A lengthy etymology is called for particularly when discussion sheds some special light on other than merely linguistic facts. A classic example can be found, again, in philosophy.

Authors are encouraged to follow one of the above conventions for reporting etymologies.

Definitions

To learn how to write a good definition, you might consult the many good explanations found in introductory logic and critical thinking textbooks. The requirements we have will be approximately the same that you will find there; see this discussion for some helpful hints.

Perhaps most general terms in the Citizendium have more or less agreed-upon definitions. But there are many terms of which there is no agreed definition, and where the definition is in fact a central matter of dispute. This is true of many abstract concepts in the humanities and social sciences, and sometimes in the hard sciences. We must weigh two concerns: on the one hand, the desire of the user for a straightforward account of the topic; on the other hand, an unbiased article, i.e., one that does not violate our Neutrality Policy.

There are several acceptable ways to solve this problem:

• Provide a single vague definition, in plain terms, which does not engage the main topics of dispute.
• Provide a quick run-down of several main definitions.
• Explicitly discuss the difficulty of defining the term; provide examples.

It is rarely if ever acceptable, however, to begin an article with just one idiosyncratic definition when there are many importantly different definitions--particularly when our opening with that definition would imply an endorsement by the Citizendium of a particular controversial view. If for whatever reason this were to be the only reasonable way to begin an article, one would have to qualify the definition. One might say that it is so-and-so's definition, that we (the Citizendium) are using the definition in order to give the reader a rough idea of the concept, but that there are many other ways of understanding the concept, and that we do not particularly favor this one.

The first paragraph

The first paragraph of articles should typically (not always: see above) begin with either a definition or a description of that for which a particular thing is best known. The first paragraph should always contain a concise and neutral answer to the question, "Why is this topic important (as important as it is)?" or "How does this topic figure in its domain?" If the topic is a person, say what the person is best known for. If an event, summarize its most important impact. If a place, describe at least a few things that make it notable (e.g., a famous corporation, park, seat of government, or a prominent historical fact).

As to rest of that opening paragraph, typically, it should begin a narrative, and be written in an interesting and informative style. It should not simply be a summary of facts stated within the main body of the article. It should attempt to describe a concept that ties together the entire article into a cohesive whole.

It should also encourage reader interest.

The introductory section

Articles begin with an introduction. The introductory section of an article (or, what comes before the first section marker) should at least give background necessary for purposes of understanding the rest of the article. What else an introduction might accomplish depends on the article. Generally, what sort of introduction is needed depends entirely on the subject matter and the approach that the article takes. For example, if the article concerns some abstruse concept, the entire introductory section might be devoted to clarifying the concept. If the article itself is primarily a narrative, the introduction would do "stage setting" for the narrative, such as introducing characters and preparing readers for key events. If the article concerns a controversy, then the introduction might characterize the controversy in a general way, introduce key players, define positions, or do other such stage-setting.

It is acceptable for the introduction to be a summary of the topic itself, that is, to sum up the information found in the article. This is not necessarily the best use of the space, however. Authors are asked to consider whether a summary of the information found in the article clarifies matters for the user particularly; often, the answer will be "no."

In fact, however, a brief outline of the article structure--as distinguished from a summary of the information contained in the article--is preferable when the article is particularly long. If the introduction contains such an outline, the summary should come at the end of the introduction.

The structure of the article body

Narrative coherence and flow

Articles should be written to be read all the way through. To be most attractive to readers, they need a unifying plan, or a narrative, which lends coherence and flow and invites readers to keep reading. This means that articles should not be modular or mere collections of facts that can easily be reshuffled.

But this is not an absolute rule that must be followed at all costs. Certain parts of articles may stand-alone, such as tables of supporting reference material or useful lists. Contributors should bear in mind, however, that such material should not "speak for itself." For example, an article might include a timeline, a list of subdisciplines, or a list of leading examples. If material is important enough to include in the article, then some of it should be important enough to be at least summarized in the narrative itself.

Moreover, sometimes a topic involves two or more different kinds of information with no plausible way to string them together into a single narrative. In that case, it is all right to have a break in the article between the separate narratives.

Some articles in Wikipedia, particularly about disciplines and other broad topics, are in the form of a list of summaries of subtopics. For example, an introduction to physics might consist of a series of sections listing the subject's different branches, each with its own introduction. This is to be avoided: a mere list of subtopics with introductions will rarely if ever succeed in effectively introducing the topic itself. It is preferable to choose an approach that will encompass the diverse subtopics--although doing so may require considerable creativity.

An imperfect indicator that the article has little narrative coherence is that it has a long series of short sections, as does this Wikipedia article. Generally, it is important to avoid overusing section titles (see below).

A central task of Citizendium editors is to provide leadership in deciding a unifying plan for articles on topics of their expertise. The plan can be discussed on the article's talk page, if it is not obvious from reading the article itself. Indeed, particularly for longer articles, it may help to conclude the introductory section with a summary that makes the article's plan clear.

Prioritization of article sections

As a general rule, to which there are many possible exceptions, information that is most important, fundamental, or earliest should be presented first. Major achievements of individuals should be presented before minor ones; the basic tenets of a theory or system of thought should be presented before derivative ones; earlier events should be recounted before later ones. Where there is disagreement as to what is most important, the order can be determined by reference to the views of those concerned, or the "constituency" of the article, and with special but not exclusive weight being given to expert opinion.

The main category of exception will probably be due to the order in which sections should appear as determined by the article plan, or by a standard order for the kind of article that it is. For example, an article that recounts the achievements of Abraham Lincoln in historical order would put the Emancipation Proclamation near the end of the article. But the Emancipation Proclamation is one of Lincoln's most important achievements, and so we would seem to want to place this first. A suitable compromise would be to have a paragraph about the Emancipation Proclamation in the introductory section of the article, or in a "Major Achievements" section that would come immediately after the introductory section.

Section titles

Section titles should be descriptive, lowercase, and necessary. A new section is rarely needed for fewer than three paragraphs; but a single section could be suitable for considerably more than that.

Many and frequent section headings are sometimes used to structure an otherwise disconnected collection of data. A plethora of headings are really not necessary in a well-organized narrative, as this "Biology" article demonstrates.

Top-level headings are created with two equals signs, like this (but flush left):

== Differences in style, approach and tone ==

Subsection headings (necessary only for very long sections) are created using three equals signs. We avoid headings surrounded on both sides by just one equals sign, because that will produce the same font size as the article title. It is not necessary to bold section titles.

Standardized information

We might say that there are some articles that have a standardized structure. If there is to be an article about every species on Earth, that is over one million articles, it is probably most convenient for the user to have a standard order in which facts are presented. Other kinds of articles that might benefit from some standardization would be biographies and articles about countries, cities, and other geopolitical areas.

Citizendium workgroups will settle ultimately on any such standard practices. Individual contributors may make proposals, but only workgroups, working according to a procedure yet to be decided, may actually settle upon proposals.

It will be important not to impose too much standardization, for the simple reason that standardization tends to work against readability and narrative flow. Moreover, within any given category, there are bound to be many exceptions and much variation. Any proposals for standardization should bear this in mind.

End matter

There are several standard kinds of end matter that are appropriate or even, in some cases, strongly recommended. A newly adopted scheme for organizing ancillary material controls the presentation of most of the material covered in this section; see CZ:Subpages.

External links

External links are preferably bulleted and neutrally annotated. "Deep links" to the page or section of a website most relevant to a given topic are preferable to links to entry pages that are several mouseclicks away from the most relevant content.

Links to external websites are not to be placed within articles themselves. The main reason for this rule is simply that it is poor style: external links belong in footnotes. Moreover, always link words and phrases to Citizendium articles rather than external sources of information about the word or phrase--even if we still lack an article on the subject.

We have rules against self-promotion in our policy on topic informants, and similarly, contributors are not to add links to websites that they manage, unless it is evident from a Google search (or other adequate proof) that the website is in fact a leading and reliable source of information on a topic.

References

The Citizendium requires references (also called citations or' 'footnote) in about the same quantity, and for about the same reasons that references are used in specialized academic encyclopedias. Generally, the following are categories of statements or claims that either require, or might at least benefit from, support by a reference:

• direct quotations
• claims with unique sources (such as survey results, or the finding of a particular paper)
• implausible-sounding but well-established claims
• claims central to the article

Note that references are not needed for information that is common knowledge among experts. Please only very sparingly use multiple references for a single sentence.

An informational note may be included as a reference in order to make important clarifications of the text, when including the clarification in the text itself would break the flow of the discussion. Such notes are to be used only sparingly--not more than a few in any given article. They should not be used to state opinions.

See Reference help for more details.

Bibliography subpage

See CZ:Bibliography for more detailed coverage.

This is an annotated bibliography: books, articles, editions and other material that, in the opinion of Citizendium authors represent the most important, and useful texts, clarifying why an item is listed ("one of the most commonly used texts in this field"; "the paper which originally defined the concept"). For example, historical topics should list and annotate the leading published sources for information on a topic, and articles about authors should have a list of major works. If all or part of an item is available online, the annotation should indicate where and if possible provide the link. (Here are the citation templates.)

Publications cited in the footnotes can also be included in the bibliography. Unpublished materials and archival sources are generally not included in the Bibliography unless they are accessible online.

Note, however, that books consulted during writing should not be listed here unless they meet the other criteria for listing.

How to write annotations is discussed at length by the Library of Congress publication Creating an Annotation.

Further reading

Long complicated articles can have a long, complicated bibliography page. They should also have a "Suggested reading" section at the end of the main article that presents 5-10 publications that are most suitable for beginners on the topic, especially if they are on the web, or available at the average library.

Annotations are recommended to help users. For example, "one of the most commonly used texts in this field"; "the paper which originally defined the concept". If there is a controversy indicate what side the item represents.

Source texts or Works

Historical topics should list and annotate the leading published, written sources for information on a topic. Similarly, articles about authors should have a list of works.

Subtopics and Related topics

Rather than use categories, as Wikipedia does, contributors can compile lists of "Subtopics" and of "Related topics". These should go on the Related Articles subpage. Right now, many articles have "See also" sections which will have to be moved to the subpage eventually. For more information, see CZ:Related Articles.

Categories

For ease of editing by other contributors, categories should be placed at the bottom of the page.

Currently, there are only a very small number of categories that are widely used on article pages. These include Category:CZ Live, the various workgroup categories, and Category:Needs Workgroup.

Please do not create new Wikipedia-style subject categories. If a category has already been created, we will not delete it in the interests of preserving information, but we may at some future date start an initiative to add "Subtopics" and "Related topics" and "List of"-type pages so as to perform a similar function to category lists.

Grammar, spelling, punctuation, and usage

To draft.

Please refer to Strunk and White's Elements of Style for basic points--if, for example, you are a high school or college student and have never read it, or if you are not a particularly experienced writer, you really must do so. (All right, not really, but it's a great idea. The first edition, which is still quite useful, is available here.)

For American English articles, please consult The Chicago Manual of Style for matters of formatting, punctuation, and the like. Consult Garner's Dictionary of American English Usage for issues of usage.

For British English articles, consult Fowler's Modern English Usage for issues of usage. Americans will also find this very useful. (We haven't settled upon a manual for formatting, punctuation, etc., of British English.)

Miscellaneous style guidelines

Craft articles for maximum readability

Craft articles for maximum readability. Many topics are inherently complex and impossible for a nonspecialist fully to understand. Nevertheless, our task is to write at the university level. Therefore, if a difficult or advanced piece of text can be written in a way to make it more accessible to educated nonspecialists, then it should be.

Scientists, business people, lawyers, and academics are famous for writing mumbo-jumbo that is decipherable only by people in their fields. But, as this is a general encyclopedia, not a single topic encyclopedia, is our obligation to "translate" the jargon of a specialized field, so far as is possible, into elegant English prose.

Even if an article concerns some very abstruse topic, the details of which no one but specialists can be expected to understand, if there is a way to introduce some fundamental aspect of the topic that is accessible to nonspecialists, then the article should begin with such an introduction. For example, the details of quantum mechanics cannot be expected to be understandable by anyone but physicists, but there are certain experiments and analogies that can be used to introduce the topic: if such explanatory devices, accessible to the layperson, are ready to hand, then we should make use of them.

Write lively prose, not "encyclopedese"

The task of writing an encyclopedia brings out a natural tendency in some writers to make prose dull--perhaps it is the influence of all those boring encyclopedia articles we read as children. But our writing needn't be like that. We can, and should, give our prose personality and punchiness. (And others should be careful not to rewrite such prose so that it loses its personality!)

Many writers today have taken William Strunk's pithy injunction, "Omit needless words," to heart. When applying this often excellent advice to others' words, however, writers will sometimes dogmatically insist on omitting words the function of which they do not fully appreciate. For instance, one might replace "It was Aristotle among the ancient Greek philosophers whose works are voluminous" with "Aristotle wrote voluminously," halving the number of words--surely a victory in the fight against needless words. But the former formulation might be more apt: the idea is that many people know (or perhaps should know) that there was an ancient thinker who is famous for having voluminous works. That thinker was Aristotle. Strunk's advice is excellent, and tightening up flabby verbiage is one of the most needful improvements we can make. We must simply not go so far as to denature our prose entirely: we want our writing to be readable and lively, not encyclopedese.

Another common stylistic rule would have us use simple Anglo-Saxon words rather than hifalutin, impressive-sounding Latin words. This is usually good advice too--except when it's not. The tendency to oversimplify language results in many a dull textbook and encyclopedia. We want our articles to be accessible, but this does not mean that we should prefer a merely adequate word to a really apt word, simply because the apt word is a bit more obscure.

Link copiously, but relevantly

One of the great strengths of using a wiki to develop an encyclopedia is the tremendous ease with which articles can link to other articles. Links invite knowledge-seekers to follow their interests wherever they might lead. Links permit serendipitous discoveries, which is, after all, one of the great attractions of reference works generally. So, without these links, the product as a whole is considerably less interesting. Therefore, the Citizendium officially encourages copious interlinking of articles.

But it is possible to take this advice to an absurd extreme--linking so many words that many inappropriate links are created, links that distract rather than help.

Therefore, there is a general (not infallible) rule for determining whether a link is appropriate or helpful:

If our target audience would find that the article linked-to illuminates the present article, then we should link to it.

Someone looking at an article about ducks might well find articles on anything bird-related, such as wings, quacking, and feeding ecology illuminating. Similarly, other things that are related only in an ancillary way, such as parks and hunting, shed light on the topic of ducks. But in passing, the article might use completely unrelated, common English words, such as "argument" or "landscape." Someone reading about ducks needs only to know the meaning of these words; if one learns all there is to know about arguments or landscapes, one does not learn much of anything that helps to understand the article about ducks.

If, however, the "duck" article happened to contain the phrase "The War of the Roses," then despite the fact that that topic has little to do with ducks, we should nevertheless link the phrase--The War of the Roses--simply because it is unknown to a significant part of our target audience. Note that this is not inconsistent with the rule: our target audience would find the "War of the Roses" article illuminating, not because it sheds light on ducks, but because it clarifies the meaning of a perhaps obscure phrase that just happens to be used in the "duck" article.

Do link to nonexistent articles

In order to build out the Citizendium, it is very important to add links--despite their "ugliness"--to articles that do not yet exist. Such links invite people to build out the Citizendium, by making it clear to everyone that an article is needed. Links that lead nowhere, moreover, help us to gauge what articles are most needed: see Wanted Pages (linked on the left under toolbox > Special pages).

Link the first use only

Link only the first use of a word or phrase, not every use--unless the word or phrase is particularly relevant to the specific point being made. Thus, for example, the article about Abraham Lincoln might mention (and link to) the Emancipation Proclamation in its introductory section, but it should also link the phrase when it comes to the section about the Proclamation itself.

Don't use external links within the article body

Please don't use external links within the article body. Place them either in a footnote (if a particular page or section is relevant), in an "External links" section (if the material lives only online), or in a "Further reading" section (if the material is published, but also available online).

It is hard to deny that external links (i.e., links to pages on external websites) within the body of an article would be useful, particularly if we lack an article about something. But it is important to understand the function of red links in the Citizendium. Articles that have red links are unquestionably uglier, and not just because of a different color, but because red means nothing is available to view. However, this ugly state of unavailability is an itch that project members work to scratch; it is also an invitation to new contributors to join us in order to "turn the red links blue." If we were simply to use links to external articles, there would be rather less incentive--perhaps much less incentive--to start our own articles.

No long quotations

As a general rule, we should not use quotations that are longer than one sentence, and we should not use many quotations in any one article. The purpose of a quotation is typically to illustrate or support some point. Quotations are, therefore, texts that support the main text, which the Citizendium writes.

There are at least two main reasons for this policy against many and long quotations.

First, such quotations prevent collaboration on the substance of the text (quotations are uneditable). It is inherently biased to have an extended quote that speaks for the Citizendium, since in that case the Citizendium is made to endorse a whole series of points that are only that source's idiosyncratic views. Second, the practice of adding a long quotation cannot be generalized. If we have a long quotation that supports one point, why should we not have long quotations that support every point? There is a vast universe of books and other potentially supporting verbiage. We could find long quotations for everything, if we wanted to. Therefore, unless there is some particularly good reason to use a quotation beyond one sentence, don't do it; summarize.

The exceptions will, perhaps, be in cases where texts themselves are the primary subject of an article. Even in this case, extended quotations are to be used sparingly and only with excellent justification.

For further reading

• Sage advice on writing CZ articles.